Docker

Wireface Chat is one container: the server, the widget, the admin panel, these docs and the face engine. It listens on port 8800 and keeps everything it stores in /data.

With Docker Compose

You need Docker with Compose 2.24 or later. From a copy of the repo:

cp .env.example .env                        # then set PUBLIC_URL and anything else you need
docker compose -f docker/compose.yml up -d  # builds the image the first time (a few minutes)
docker compose -f docker/compose.yml logs wireface-chat

The log prints the first-run setup token. Open /admin/setup on the server and follow the quick start.

What docker/compose.yml sets up:

• the wireface-chat service, built from docker/Dockerfile, restarting unless stopped;
• port 8800 published on the host;
• the repo root's .env passed to the container as environment variables, if the file exists (see Configuration);
• a named volume, wireface-data, mounted at /data: the database, uploaded files and the generated master key live there. Back it up (see Backups).

The image sets NODE_ENV=production, HOST=0.0.0.0, PORT=8800 and DATA_DIR=/data, runs as the unprivileged node user, and has a health check on /healthz.

When a reverse proxy on the same machine handles HTTPS (as it should for anything public), publish the port on localhost only, so the server isn't reachable around the proxy:

    ports:
      - "127.0.0.1:8800:8800"

Useful commands:

docker compose -f docker/compose.yml logs -f wireface-chat   # follow the log
docker compose -f docker/compose.yml restart wireface-chat   # after changing .env
docker compose -f docker/compose.yml down                    # stop (the data volume stays)

With plain Docker

docker build -f docker/Dockerfile -t wireface-chat .
docker run -d --name wireface-chat -p 8800:8800 -v wireface-data:/data \
  -e PUBLIC_URL=https://chat.example.com wireface-chat

Without Docker

You need Node.js 24 and pnpm 10. From the repo root:

pnpm install
pnpm build          # the server, widget, admin panel and packages
pnpm docs:build     # these docs (optional)
NODE_ENV=production DATA_DIR=/var/lib/wireface pnpm start

pnpm start runs the server from apps/server. It finds the built widget, admin panel, docs and face engine in the repo, and reads .env from apps/server or the repo root. Without DATA_DIR, data goes in apps/server/data. Use your init system (systemd, a process manager) to keep it running.

One process

Run a single server process per database. It keeps live conversations, voice sessions and rate limits in memory, so several instances behind a load balancer aren't supported in this version.

Checking it's up

GET /healthz answers { "ok": true, "version": "0.1.0", "uptime": 1234 } (uptime in seconds).