Deployment

From mnema-talk v3.3.13, rendered on this site.

Everything around running a released image: which ports to open, which image tag to follow, supported platforms and the update paths. The configuration reference, reverse proxy, TURN and monitoring are in operations.md; step-by-step upgrades and rollback are in upgrade.md; backups are in operations.md.

New here? Start with the quick start; platform specifics (Synology, Unraid, a plain VPS) are in platform-notes.md and all updating is on one page, updating.md. The steps below are the manual, platform-independent reference; the setup assistant (docker run --rm -it --user "$(id -u):$(id -g)" -v "$PWD:/out" ghcr.io/mnema-xyz/mnema-talk setup, run in an empty folder) does the "Fresh install" part for you.

Ports

The full reference, with every inbound port, every outbound connection and what must stay closed, is ports.md. In short, with the default settings forward TCP 443 to the reverse proxy, UDP 50000-50050 for voice and video and UDP and TCP 3479 for the built-in TURN relay. Do not forward 8080 (published on 127.0.0.1 only), PostgreSQL or SeaweedFS.

UDP socket buffers and the memory limit

Socket buffers. The server asks the kernel for 4 MiB of receive and send buffer on its media and relay sockets, because a screen frame arrives as a burst of ten or more packets and a keyframe as 40 or more. The kernel grants at most net.core.rmem_max (receive) and net.core.wmem_max (send) of the host; the usual default of about 208 KB silently caps the request and bursts are then dropped when the server is briefly short of CPU. On a host with many viewers, raise both (the values are bytes):

sudo sysctl -w net.core.rmem_max=8388608 net.core.wmem_max=8388608
# keep them across reboots:
printf 'net.core.rmem_max=8388608\nnet.core.wmem_max=8388608\n' | sudo tee /etc/sysctl.d/90-mnema-udp.conf

Docker containers on the default bridge share the host's limits. To see whether packets were dropped, compare RcvbufErrors and SndbufErrors before and after a call: nstat -az UdpRcvbufErrors UdpSndbufErrors.

Memory limit. At start the server reads the container's memory limit (cgroup v2 memory.max, else cgroup v1) and tells the Go runtime to keep its heap within 85% of it, so the garbage collector works harder near the limit instead of letting the kernel reclaim or kill the process. It logs what it chose (memory limit: ...). An explicit GOMEMLIMIT in the environment is left as it is; without a container limit nothing is set.

Fresh install

A new host needs Docker with Compose and nothing else: the compose file and .env.example of the release are the whole deployment (no clone, no build). The commands install the latest release; to pin another, set VERSION yourself.

mkdir mnema-talk && cd mnema-talk
VERSION=$(curl -fsSL https://api.github.com/repos/mnema-xyz/talk/releases/latest | sed -n 's/.*"tag_name": *"v\([^"]*\)".*/\1/p')
[ -n "$VERSION" ] || { echo "could not read the latest version; set VERSION=x.y.z yourself" >&2; false; }
base=https://raw.githubusercontent.com/mnema-xyz/talk/v$VERSION
curl -fsSLO "$base/docker-compose.yml"
curl -fsSL "$base/.env.example" -o .env
chmod 600 .env

Edit .env: the values below are required in production, and the server refuses the public placeholders from .env.example. (The setup assistant in quick-start.md generates this file and the secrets for you.)

The same image is also published on Docker Hub as docker.io/mnemaxyz/mnema-talk (the older docker.io/msch128/mnema-talk carries the same image; same digest and signature, see Verifying a release image); GHCR stays the primary reference used in this guide.

VariableSet it to
MNEMA_IMAGEghcr.io/mnema-xyz/mnema-talk:X.Y.Z (or :X.Y, or :latest; see Updates)
PUBLIC_URLThe https:// address members open. An http:// address starts, with a warning (see operations.md).
JWT_SECRETopenssl rand -hex 32
POSTGRES_PASSWORDopenssl rand -hex 16 (compose builds DATABASE_URL from it)
S3_ACCESS_KEY, S3_SECRET_KEYAny letters and digits (secret: at least 8 characters)
ADMIN_INITIAL_PASSWORDThe Owner's password, at least 14 characters; remove it after the first start
INITIAL_LANGUAGEOptional, en (default) or de: the language of the default category and channel names. Only the first start uses it.

Then start and check it (the admin Status tab's setup checks list anything still missing):

docker compose config -q
docker compose up -d --wait        # pulls the images, returns once everything is healthy
curl -fsS http://127.0.0.1:8080/api/health

Sign in as the Owner (ADMIN_USERNAME, default admin) and create invite codes. Put a reverse proxy with TLS in front, forward the voice UDP range (see Network ports) and set up backups before inviting anyone. CI runs exactly these steps against the image it just built (scripts/fresh-install-check.sh).

After the first start

The Owner's first sign-in shows a Get started list under the channel header: name the community, invite people (a button creates and copies a 7-day link), review the channels, set up voice, check the status page and, optionally, write rules. The steps tick themselves from what exists on the server, or once you have opened the channels or status page. Close the list with the cross; the server menu brings it back (Get started checklist). A community that already had members when the Owner first looked starts with it closed. The state is kept per Owner (GET/PUT /api/admin/first-run).

  • Create the first invite: Admin console → Invites. Members register with that code; there is no public registration.
  • Set the community name and the rules new members accept (Admin console → Welcome & rules). The switch for direct messages (on by default) and the sign-out after inactivity are on their own page, Admin console → Sign-in & messages.
  • Give moderators their rights through roles: Manage reports (the Reports tab) and Kick members are off for @everyone and for every role until you grant them (roles).
  • Optional features, each off until you configure it: e-mail and password reset (SMTP_*), Web Push (keys are generated on the first start; PUSH_VAPID_SUBJECT is optional), two-factor sign-in (members switch it on themselves), the API reference page (API_DOCS_ENABLED), a TURN relay (turn profile) and the update button (autoupdate profile). All variables: operations.md.
  • Check what your host can carry: capacity.
  • Browsers that can join Talks: README.

Optional parts (Compose profiles)

A profile is a group of optional services in docker-compose.yml that start only when you enable them. Without profiles you get the app, PostgreSQL and SeaweedFS. To enable one:

  • put COMPOSE_PROFILES=autoupdate (several: autoupdate,turn) in the .env next to the compose file; this also works in Synology Container Manager, or
  • start with docker compose --profile autoupdate up -d.
ProfileStartsYou want it whenPorts it opensExtra .env settings
autoupdateupdater and recreator (they hold the Docker socket)You want an "Update now" button in Admin > SystemNone (internal network; outbound HTTPS to ghcr.io and Sigstore)UPDATER_TOKEN (openssl rand -hex 32, 32+ characters), a released MNEMA_IMAGE
turncoturn, an external TURN server on host networkingYou prefer a separate relay process or public relay ports; the built-in relay on port 3479 needs no profile3478 UDP and TCP, 49152-49200 UDPWEBRTC_TURN_URLS, WEBRTC_TURN_SECRET (16+ characters), optionally WEBRTC_TURN_REALM (coturn)

The setup assistant can enable autoupdate for you (it asks, or pass --auto-update). Read the sidecar's threat model first. After changing profiles run docker compose up -d.

Running a released image

Instead of building on the server, use a published image: set MNEMA_IMAGE in .env (the compose file uses it for the app service) and start without --build:

# .env
MNEMA_IMAGE=ghcr.io/mnema-xyz/mnema-talk:X.Y   # or :X.Y.Z (pinned) or :latest

docker compose pull app && docker compose up -d

Then update with docker compose pull app && docker compose up -d app, or from the admin console (see Updates).

Hardware by size

What a server needs depends on the largest Talk you run, not on how many members have an account: chat is cheap (1,000 connected chat sessions used about 0.7 of a core and 100 MB in the benchmark), while every video stream the server forwards costs CPU, memory and upload bandwidth. The rows below come from the sizing guide and describe one Talk at a time with 3 speakers, plus the screen share or cameras named.

TalkCPU to plan forRAM (APP_MEM_LIMIT)Server upload
About 10 members, voice only0.1 core1 GB (the default)1 Mbit/s
About 25 members, with 1 screen share (1.5 Mbit/s)0.5 core1 GB (the default)about 51 Mbit/s
About 50 members, 1 screen share and 4 cameras (300 kbit/s each)1.4 cores1 GB (the default)about 180 Mbit/s
About 100 members, voice and 1 screen share1.8 cores1 GB (the default)about 208 Mbit/s
More than that, or several Talks at onceMeasure it (benchmark)

CPU is in cores of an Intel N100, the benchmark's test host, and already doubled from the fitted value because bursts lose packets well before 100 % load. A modern server CPU is usually at least as fast per core, but that was not calibrated on other hardware. The upload column is what the server's internet connection must carry while the Talk is running.

Upload bandwidth, not CPU, is usually the limit for video on a home connection. A screen share watched by 25 members already needs about 51 Mbit/s upstream, more than many home lines offer, and a VPS with a fast uplink or fewer simultaneous viewers solves that where a faster CPU does not.

Three tools help you check your own server against these rows. Admin > Status has a capacity panel with the live CPU, memory and outgoing traffic of the server and, per kind of Talk (listening, everyone talking, a screen share, a video call, text only), about how many people fit and whether CPU, memory or upload runs out first. Test my connection (Settings > Audio, and the Status tab) reports roughly the server's upload and what it means in members with a screen share, when you run it from outside the server's network. And VOICE_UPLOAD_LIMIT_MBIT (off by default, see operations) tells the server the speed of its line: it then keeps its outgoing media under about 85 % of it by lowering the quality of screen shares and cameras, never audio.

Shapes with many cameras and 100 members did not hold on the test host (they lost packets), and several Talks at once and longer runs were not measured. For anything beyond the table, run the measurement on your own hardware: see the method, the caveats and the way to reproduce it in the benchmark.

Supported platforms

Images are published for linux/amd64 and linux/arm64 (e.g. Raspberry Pi 4/5 with a 64-bit OS); Docker picks the right one. The rest of the stack (postgres:18-alpine, chrislusf/seaweedfs, coturn/coturn) is published for both as well. linux/arm/v7 (32-bit ARM) is not built: those images exist for it too, but the server doesn't compile for 32-bit targets yet (a 64-bit constant in internal/db overflows int). Builders cross-compile the Go binary on the build machine, so a multi-arch build needs no QEMU: docker buildx build --platform linux/amd64,linux/arm64 .

Health probes for other orchestrators

The shipped Compose file needs nothing from this section: its health check calls GET /api/health, "healthy" means "ready for members", and plain Compose never restarts a container for being unhealthy.

An orchestrator that acts on a probe needs two different questions answered:

ProbeEndpointMeaning
Liveness (restart when it fails)GET /api/health/live200 whenever the process serves requests; it asks neither the database nor object storage.
Readiness, startup, monitoringGET /api/health200 when the database answers and object storage is reachable, else 503 with what is down in unavailable. Storage is checked live (one HEAD on the bucket, at most every 10 s, 2 s limit), so it also reports storage that fails or returns while the server runs. One failed probe is not reported; two in a row are (the second is asked after 3 s), and a successful one clears it at once.

Do not use /api/health as a liveness probe. It answers 503 while object storage is down, although chat and Talks still work then; a restart would not bring storage back and would end every running Talk. The container health check (Docker or Compose, interval 30 s, 3 retries) calls /api/health: during a storage outage that lasts more than a minute or so it turns the container unhealthy, which only labels it (nothing restarts it); a blip of a single failed probe does not. One /api/health call takes at most about 4 s (database ping plus one storage probe), under the 5 s check timeout. For Kubernetes:

livenessProbe:
  httpGet: { path: /api/health/live, port: 8080 }
  periodSeconds: 30
readinessProbe:
  httpGet: { path: /api/health, port: 8080 }
  periodSeconds: 10

The same holds for Docker Swarm and for an autoheal container: point whatever restarts on failure at /api/health/live. Both endpoints are public and are described in operations.md.

Pull-based deployment

Deployment to a LAN/self-hosted server stays manual and pull-based: GitHub's hosted runners cannot reach a server inside a private network, so nothing pushes to it. Bump the tag (or pull :X.Y / :latest) when you want to update. Database migrations run automatically at startup.

If the GHCR package is private (the default for a newly published package), either make it public once under the package's settings on GitHub, or run docker login ghcr.io on the server with a token that has read:packages.

Updates

Everything about updating is on one page: updating.md. It covers the backup, the update check and the optional "Update now" button, which image tag to follow (:X.Y, :latest or a pinned :X.Y.Z; GHCR has no :X tag), the command-line steps, verification and rollback. Per-version notes for operators: upgrade.md.

Something wrong on this page? Tell us.