Docker Compose

The fastest way to self-host Gryt. Everything runs from pre-built images published to GitHub Container Registry — no need to clone any repos or build anything.

What's included

Most users connect via the Gryt desktop app (available for Linux, macOS, and Windows).

Quick start

mkdir gryt && cd gryt
curl -Lo docker-compose.yml https://raw.githubusercontent.com/Gryt-chat/gryt/main/ops/deploy/compose/prod.yml
curl -Lo .env https://raw.githubusercontent.com/Gryt-chat/gryt/main/ops/deploy/compose/.env.example

mkdir gryt && cd gryt
wget -O docker-compose.yml https://raw.githubusercontent.com/Gryt-chat/gryt/main/ops/deploy/compose/prod.yml
wget -O .env https://raw.githubusercontent.com/Gryt-chat/gryt/main/ops/deploy/compose/.env.example

# Give your server a name
SERVER_NAME=My Gryt Server

# Set a real secret in production
JWT_SECRET=<run: openssl rand -base64 48>

# Allowed origins (desktop app + hosted web client)
CORS_ORIGIN=http://127.0.0.1:15738,https://app.gryt.chat

docker compose up -d

Architecture

Configuration reference

Image versions

Images default to latest. Pin a specific version for reproducible deploys:

SERVER_VERSION=x.y.z
SFU_VERSION=x.y.z
IMAGE_WORKER_VERSION=x.y.z  # only if running image-worker

Browse available tags at github.com/orgs/gryt-chat/packages.

Beta channel

The Gryt server, SFU, image worker, and web client publish a latest-beta image. To follow the beta channel, set the version variables in .env:

SERVER_VERSION=latest-beta
SFU_VERSION=latest-beta
IMAGE_WORKER_VERSION=latest-beta

# Only used when the optional web profile is enabled
CLIENT_VERSION=latest-beta

Then pull and restart the stack:

docker compose pull
docker compose up -d

latest-beta moves whenever a new beta is published. For a predictable deployment, replace it with the exact tag shown in the package registry, such as 1.2.3-beta.4. Pin each service separately because its version may differ from the others.

A beta server does not change any other server a user belongs to. The risk is at the client-server boundary: a stable client may not understand a beta-only event or endpoint, and a beta client may expect something a stable server does not provide. Run the matching beta desktop client when testing a beta server.

People joining cannot rely on the client to identify a self-hosted server's release channel. Add Beta to SERVER_NAME and mention the version in SERVER_DESCRIPTION so they know what they are joining:

SERVER_NAME=My Gryt Server (Beta)
SERVER_DESCRIPTION=Testing Gryt 1.2.3-beta.4

Image Worker

Ports

Server

If you set SERVER_PASSWORD, keep it stable. Changing it may require restarting the SFU, because the SFU caches the password per server ID.

Changing the server owner (CLI)

The first user to join a brand-new server becomes the owner/admin automatically.

To change the owner later, run:

docker compose exec server node admin-setOwner.js --grytUserId <keycloak_sub>

<keycloak_sub> is your Gryt user ID. You can find it in the desktop app or web client by going to Settings → Profile and scrolling to the bottom.

Authentication

WebRTC / NAT

Storage

Production checklist

TLS with Caddy (recommended)

The simplest way to add HTTPS is Caddy — it handles certificates automatically.

Add this to your docker-compose.yml:

services:
  caddy:
    image: caddy:latest
    container_name: gryt-caddy
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy-data:/data
    networks:
      - gryt
    restart: unless-stopped

volumes:
  caddy-data:

And create a Caddyfile:

api.example.com {
    reverse_proxy server:5000
}

sfu.example.com {
    reverse_proxy sfu:5005
}

Then update your .env:

CORS_ORIGIN=http://127.0.0.1:15738,https://app.gryt.chat
SFU_PUBLIC_HOST=wss://sfu.example.com

# Multi-network example (LAN party + public):
# SFU_PUBLIC_HOST=wss://sfu.example.com,ws://192.168.1.100:5005
# ICE_ADVERTISE_IP=203.0.113.10,192.168.1.100

LAN optimization

# Your server's LAN IP (find it with: hostname -I | awk '{print $1}')
ICE_ADVERTISE_IP=192.168.1.100
SFU_PUBLIC_HOST=ws://192.168.1.100:5005

For mixed setups where some users are on the LAN and others connect over the internet, use comma-separated values. The client automatically pings each SFU endpoint and picks the fastest:

ICE_ADVERTISE_IP=203.0.113.10,192.168.1.100
SFU_PUBLIC_HOST=wss://sfu.example.com,ws://192.168.1.100:5005

Managing the stack

# View logs
docker compose logs -f

# View logs for a single service
docker compose logs -f server

# Restart a service after config change
docker compose restart server

# Update to latest images
docker compose pull && docker compose up -d

# Update a single service to a specific version
SFU_VERSION=x.y.z docker compose up -d sfu

# Stop everything
docker compose down

# Stop and remove all data (clean slate)
docker compose down -v

Health checks

All services expose health endpoints. Check the stack health:

curl http://localhost:5000/health   # server
curl http://localhost:5005/health   # sfu

The image worker's health endpoint (GET / on port 8080) is internal-only — it's used by Docker's built-in healthcheck and is not exposed to the host.

Or use docker compose ps to see the health status of all containers.

Monitoring

Both the Server and SFU expose Prometheus metrics at /metrics. Enable the optional monitoring stack (Prometheus + Grafana) with:

docker compose --profile monitoring up -d

Grafana is available at http://localhost:3000 (default login: admin / admin).

See the full Monitoring guide for configuration, available metrics, and recommended dashboards.

Upgrading

# Pull the latest images
docker compose pull

# Recreate containers with new images
docker compose up -d

# Verify
docker compose ps

To upgrade to specific versions, edit the *_VERSION vars in .env:

SERVER_VERSION=x.y.z
SFU_VERSION=x.y.z

Then run docker compose up -d.

Running more than one server

One compose file can run as many Gryt servers as you like. They are fully separate — their own channels, members, invites and roles — and they share the expensive parts of the stack.

What each extra server needs:

What they share, safely:

• One SFU. Voice rooms are namespaced per server, so a single SFU serves all of them. This is how gryt.chat itself runs — three servers, one SFU.
• One MinIO, one bucket. Every stored object is keyed by a UUID, so two servers writing to the same bucket cannot collide. Give them separate buckets if you would rather keep the storage separable.

Adding a second server

Copy the server and image-worker blocks, and change four things — the container names, the port, the data volume, and the name:

services:
  server-2:
    image: ghcr.io/gryt-chat/server:${SERVER_VERSION:-latest}
    container_name: gryt-prod-server-2
    network_mode: host
    extra_hosts:
      - "sfu:127.0.0.1"
      - "minio:127.0.0.1"
    environment:
      PORT: 5010                      # a free port on the host
      SERVER_NAME: My Second Server   # must differ from the first
      DATA_DIR: /data                 # its own volume, mounted below
      JWT_SECRET: ${JWT_SECRET_2:?Set JWT_SECRET_2 in .env}
      SFU_WS_HOST: ws://sfu:${SFU_PORT:-5005}   # the same SFU
      S3_BUCKET: ${S3_BUCKET:-gryt}             # the same bucket
      IMAGE_WORKER_URL: http://127.0.0.1:8082
      # …every other variable copied from the first server
    volumes:
      - gryt-prod-server-2-data:/data

  image-worker-2:
    image: ghcr.io/gryt-chat/image-worker:${IMAGE_WORKER_VERSION:-latest}
    container_name: gryt-prod-image-worker-2
    ports:
      - "127.0.0.1:8082:8080"         # a different health port
    environment:
      DATA_DIR: /data
      S3_ENDPOINT: http://minio:9000
      S3_BUCKET: ${S3_BUCKET:-gryt}
      # …credentials copied from the first worker
    volumes:
      - gryt-prod-server-2-data:/data # the same volume as its own server

volumes:
  gryt-prod-server-2-data:

ops/deploy/compose/prod.yml ships this as a commented-out block, so uncommenting it is usually faster than writing it out.

Using external S3

To use an external S3-compatible provider (AWS, Cloudflare R2, etc.) instead of the bundled MinIO, remove the minio and minio-init services from docker-compose.yml and set the appropriate environment variables on the server service directly:

server:
  environment:
    S3_ENDPOINT: "https://<account-id>.r2.cloudflarestorage.com"
    S3_REGION: auto
    S3_ACCESS_KEY_ID: "<your-key>"
    S3_SECRET_ACCESS_KEY: "<your-secret>"
    S3_BUCKET: gryt
    S3_FORCE_PATH_STYLE: "false"