captions-deploy/docs/CONFIGURATION.md

Configuration guide

This document explains every configuration artifact that ships with the Caption Stack and how to customise it for a production deployment.

1. docker-compose.yml

The base compose file defines three core services:

Service	Build context	Port exposure (development)
caption-local	./caption-local	8765:8765
captionninja-relay	./captionninja/relay	127.0.0.1:8787:8787
captionninja-web	Nginx image (nginx:alpine)	8080:80

It is deliberately minimal – useful for quick local testing.

2. docker-compose.prod.yml

The production override adds:

• Health‑checks for all services – Docker will mark a container healthy only when the check succeeds.
• Traefik service – runs the edge router, terminates TLS, and proxies traffic to the three core services.
• Docker‑label routing – each core service is annotated with traefik.http.routers.* labels that map a hostname to the internal container port.
• Resource limits & restart policies – safer operation on shared hosts.
• Persistent letsencrypt volume – stores ACME certificates across restarts.
• Optional Basic‑Auth middleware – if the traefik-htpasswd secret exists, the routers automatically use the basicauth middleware.

Important

– Edit the hostnames in the router rules (caption.local.yourdomain.com, relay.yourdomain.com, ui.yourdomain.com) to match DNS records that point to your server.

3. traefik.yml

Static Traefik configuration (mounted read‑only into the container). Highlights:

• Entry points – web (HTTP) redirects to websecure (HTTPS).
• Let’s Encrypt resolver – uses the LETSENCRYPT_EMAIL environment variable (set in .env.production).
• API dashboard – reachable at https://<your‑domain>/dashboard/ (protected by TLS).

4. Environment file – .env.production

Create this file (git‑ignored) with at least:

LETSENCRYPT_EMAIL=you@example.com

Add any other production‑only env vars here; they will be interpolated by Docker Compose.

5. Secrets

• Relay private JSON – captionninja/relay/.caption‑ninja‑relay.private.json (ignored by Git). Contains room‑token information.
• Basic‑Auth secret – optional; generate with htpasswd -nbB <user> <pass> > secrets/traefik.htpasswd and create a Docker secret:

 docker secret create traefik-htpasswd ./secrets/traefik.htpasswd

Traefik will read the secret at /run/secrets/traefik-htpasswd.

6. Running the stack

# Initialise submodules (once)
 git submodule update --init --recursive

# Build and start production stack (Traefik will fetch TLS certs)
 docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

Verify health status with docker compose ps – all services should show healthy.

7. Updating TLS certificates

Traefik automatically renews certificates. If you need to force a renewal (e.g., after DNS changes), delete the letsencrypt volume and restart Traefik:

docker compose -f docker-compose.yml -f docker-compose.prod.yml down traefik
docker volume rm $(docker volume ls -q | grep letsencrypt)
 docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d traefik

---

For further details, see the top‑level README.md which provides quick‑start commands and troubleshooting tips.