Deployment
This guide covers how to deploy mzchat with Docker and Docker Compose.
Docker Image
Section titled “Docker Image”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:
masterfollows 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.
Docker Compose
Section titled “Docker Compose”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_dataPut the Meilisearch key in a .env file next to docker-compose.yml. Generate it with openssl rand -hex 32:
MEILI_MASTER_KEY=<random value>The web interface is served under the base path, http://localhost:8080/mzchat/ by default.
Environment Variables
Section titled “Environment Variables”| Variable | Description | Default |
|---|---|---|
PORT | Port the container listens on | 8080 |
CANONICAL_ADDRESS | Public URL of the service | http://localhost:8080 |
ASSETS_DOMAIN | Domain for serving user uploads | CANONICAL_ADDRESS |
BASE_PATH | URL prefix for the application | /mzchat |
TRUST_PROXY | Take client addresses from X-Forwarded-For, for rate limits. Enable only behind a reverse proxy. | false |
MEILI_URL | URL of the Meilisearch instance. Search is off without it. | - |
MEILI_API_KEY | Meilisearch master key | - |
JWT_SECRET | Secret for signing session tokens | Generated into /app/data/jwt.secret |
LIVEKIT_URL, LIVEKIT_API_KEY, LIVEKIT_API_SECRET | LiveKit server for voice calls. Calls are off unless the key and secret are set. | - |
S3_ENDPOINT, S3_ACCESS_KEY, S3_SECRET_KEY, S3_BUCKET | Store uploads in S3 instead of the data volume | - |
SENTRY_DSN | Send server errors to Sentry or a compatible server | - |
Volumes
Section titled “Volumes”/app/data holds everything the server writes:
chat.dbis the SQLite database.jwt.secretis the generated session signing secret, unlessJWT_SECRETis 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.