Skip to content

Deployment

This guide covers how to deploy mzchat with Docker and Docker Compose.

The mzchat-web image is published to GitHub Packages as ghcr.io/mzhang28/mzchat-web. It contains the backend server and the pre-built frontend.

CI publishes three kinds of tags:

  • master follows the latest build of the master branch.
  • v* tags match release tags in git.
  • sha-<commit> tags name one exact build.

For a server you want to keep stable, use a v* or sha- tag, so an upgrade only happens when you change the tag.

This setup runs mzchat with Meilisearch for message search:

services:
mzchat:
image: ghcr.io/mzhang28/mzchat-web:master
ports:
- "8080:8080"
environment:
# The public URL where the application will be accessible
- CANONICAL_ADDRESS=https://chat.example.com
# Set when a reverse proxy (Caddy, nginx) sits in front of mzchat
- TRUST_PROXY=true
- MEILI_URL=http://search:7700
- MEILI_API_KEY=${MEILI_MASTER_KEY}
volumes:
- ./mzchat-data:/app/data
depends_on:
- search
search:
image: getmeili/meilisearch:v1.54.3
# No published port: only mzchat needs to reach it.
environment:
- MEILI_MASTER_KEY=${MEILI_MASTER_KEY}
volumes:
- ./meili-data:/meili_data

Put the Meilisearch key in a .env file next to docker-compose.yml. Generate it with openssl rand -hex 32:

Terminal window
MEILI_MASTER_KEY=<random value>

The web interface is served under the base path, http://localhost:8080/mzchat/ by default.

VariableDescriptionDefault
PORTPort the container listens on8080
CANONICAL_ADDRESSPublic URL of the servicehttp://localhost:8080
ASSETS_DOMAINDomain for serving user uploadsCANONICAL_ADDRESS
BASE_PATHURL prefix for the application/mzchat
TRUST_PROXYTake client addresses from X-Forwarded-For, for rate limits. Enable only behind a reverse proxy.false
MEILI_URLURL of the Meilisearch instance. Search is off without it.-
MEILI_API_KEYMeilisearch master key-
JWT_SECRETSecret for signing session tokensGenerated into /app/data/jwt.secret
LIVEKIT_URL, LIVEKIT_API_KEY, LIVEKIT_API_SECRETLiveKit server for voice calls. Calls are off unless the key and secret are set.-
S3_ENDPOINT, S3_ACCESS_KEY, S3_SECRET_KEY, S3_BUCKETStore uploads in S3 instead of the data volume-
SENTRY_DSNSend server errors to Sentry or a compatible server-

/app/data holds everything the server writes:

  • chat.db is the SQLite database.
  • jwt.secret is the generated session signing secret, unless JWT_SECRET is set. If it is lost, every user is logged out.
  • uploads/ holds uploaded media, unless S3 is configured.

/meili_data holds the search index. Keep it with the database: mzchat indexes each message once, so messages indexed before the index was lost stay unsearchable.