Docker Review

Skill: Docker Review

Use this skill to review, debug, or modify VoxBento's Docker configuration. Files: docker-compose.yml, Dockerfile, mediamtx.yml.

Services Overview

docker-compose.yml
  ├── portal           → FastAPI app (built from Dockerfile)
  ├── mediamtx         → bluenviron/mediamtx:1
  ├── jitsi-web        → jitsi/web:stable-9823
  ├── jitsi-prosody    → jitsi/prosody:stable-9823
  ├── jitsi-jicofo     → jitsi/jicofo:stable-9823
  └── jitsi-jvb        → jitsi/jvb:stable-9823

volumes:
  portal-data         → SQLite DB persistence
  jitsi-web-config
  jitsi-prosody-config
  jitsi-prosody-plugins
  jitsi-jicofo-config
  jitsi-jvb-config

Portal Container

Startup command:

sh -c "uv run alembic upgrade head && uv run uvicorn fastapi_app:app --host 0.0.0.0 --port 8000"

• Alembic migrations run on every container start — idempotent and safe.
• No --reload in production (add for local dev by overriding command).

Volume mounts:

• .:/app — source mount for hot reload.
• /app/.venv — anonymous volume preserves container .venv (not overwritten by host).
• portal-data:/data — SQLite DB persistence.

Environment variables (required for production):

Health check: GET http://localhost:8000/healthz — 10s interval, 5s timeout, 3 retries.

MediaMTX Container

Image: bluenviron/mediamtx:1

Port mappings:

• 8888:8888 — HTTP (internal health, Control API accessible via port 9997)
• 8889:8889 — WHIP/WHEP
• 8189:8189/udp — WebRTC ICE/UDP
• 9997:9997 — Control API
• 8554:8554 — RTSP

Config: ./mediamtx.yml:/mediamtx.yml:ro

Key settings in mediamtx.yml:

• overridePublisher: yes — allows handoff
• alwaysAvailable paths — created dynamically via Control API

Jitsi Stack

• web: HTTPS port 8443, HTTP port 8080. BOSH_RELATIVE: "true" ensures relative paths work without SSL.
• prosody: XMPP server. JVB_AUTH_PASSWORD and JICOFO_AUTH_PASSWORD must be set in production.
• jicofo: Conference focus component.
• jvb: Jitsi Video Bridge. DOCKER_HOST_ADDRESS must be set to LAN IP on macOS; hostname -I on Linux.

Networking Notes

• Services communicate by Docker service name: mediamtx, jitsi-prosody, etc.
• MEDIAMTX_WHIP_BASE must be the browser-reachable URL (e.g. https://voxbento.example.com:8889), not the Docker internal URL. Browsers make WebRTC connections directly to MediaMTX.
• MEDIAMTX_API_BASE uses Docker internal: http://mediamtx:9997.
• MEDIAMTX_INTERNAL_BASE: http://mediamtx:8888 — for portal health checks.

Common Docker Issues

Production Hardening Checklist

• SECRET_KEY set to random 32+ char string.
• API_KEY_ENCRYPTION_KEY set if using transcription.
• ADMIN_PASSWORD set.
• DATABASE_URL set to PostgreSQL.
• MEDIAMTX_WHIP_BASE set to HTTPS public URL.
• JITSI_DOMAIN and JITSI_BASE_URL set.
• DOCKER_HOST_ADDRESS set (for JVB ICE candidates).
• JVB_AUTH_PASSWORD and JICOFO_AUTH_PASSWORD changed from default changeme.
• Remove .:/app source mount (use image with baked-in code).
• Remove --reload from uvicorn command.
• Add Caddy (provided Caddyfile) or nginx for TLS termination.