Configuration¶

Semaphore Chat is configured through environment variables. The backend reads from backend/.env and the frontend from frontend/.env.

Backend environment variables¶

Copy backend/env.sample to backend/.env to get started.

Core¶

openssl rand -base64 32

File storage¶

File uploads (message attachments, avatars, banners, custom emoji, soundboard sounds) can be stored on the local filesystem or in an S3-compatible object store. Storage is resolved per file record — switching STORAGE_TYPE only affects where new uploads land; existing files keep working from wherever they were originally stored, so mixed-storage instances (e.g. after a mid-life migration to S3) work with zero migration.

The following are only required when STORAGE_TYPE=S3 (validated at startup):

Local development with MinIO¶

The dev Docker Compose stack includes a MinIO service (S3-compatible, runs locally) behind an opt-in s3 profile so it doesn't start by default:

docker compose --profile s3 up -d minio minio-init

Then set in backend/.env:

STORAGE_TYPE=S3
S3_BUCKET=semaphore-dev
S3_REGION=us-east-1
S3_ACCESS_KEY_ID=minioadmin
S3_SECRET_ACCESS_KEY=minioadmin
S3_ENDPOINT=http://minio:9000
S3_FORCE_PATH_STYLE=true

The minio-init sidecar creates the semaphore-dev bucket automatically on first start. MinIO's web console (if you enable the console port in docker-compose.yml) is available at http://localhost:9001 with the same credentials.

LiveKit (voice/video)¶

These are optional — voice and video features are disabled if not configured.

Replay buffer¶

Configuration for the replay buffer / screen recording feature. Requires LiveKit egress to be set up.

Reverse proxy¶

If Semaphore Chat runs behind a reverse proxy (Nginx, Traefik, Caddy, a cloud load balancer, etc.), set TRUST_PROXY so that rate-limiting and session IPs use the real client address instead of the proxy's.

Common values:

See the Express proxy documentation for all supported values.

Dynamic IP watcher¶

Configuration for the optional IP watcher sidecar. See Dynamic IP support for setup instructions.

Push notifications (VAPID)¶

Web Push notifications require VAPID keys. Each instance needs its own unique key pair.

Generate VAPID keys:

docker compose run --rm backend npx web-push generate-vapid-keys

Password reset email (SMTP)¶

Self-service password reset is optional. The feature is auto-disabled — no error at startup, the reset endpoints and UI simply stay off — unless SMTP_HOST, SMTP_FROM, and PUBLIC_APP_URL are all set.

GIF search (Giphy)¶

TENOR_API_KEY from v0.4.0 is deprecated and ignored — replace it with GIPHY_API_KEY.

Background jobs (BullMQ)¶

Message-notification fan-out and link previews run on a BullMQ background queue. It reuses the app's existing REDIS_HOST / REDIS_PORT / REDIS_PASSWORD / REDIS_DB variables but opens its own Redis connection (BullMQ requires maxRetriesPerRequest: null). Processors run in-process in the backend container — no separate worker deployment is needed.

Thumbnail backfill¶

On startup, Semaphore Chat retries thumbnail generation for video files that don't have one yet (e.g. uploaded before thumbnail support existed, or whose generation failed). This is deferred and batched so it can't spike memory at boot: at most one ffmpeg frame-extraction child process runs at a time (capped at 30s), and the database working set per batch is just THUMBNAIL_BACKFILL_BATCH_SIZE rows of { id, storagePath }.

Frontend environment variables¶

Copy frontend/.env.sample to frontend/.env. The defaults work for local Docker development.

Production considerations¶

• JWT secrets — Use long, random strings. Never reuse across environments.
• PostgreSQL — Use authentication and restrict network access.
• Redis — Enable authentication and restrict network access.
• HTTPS — Always use TLS in production. Configure via your reverse proxy or Kubernetes ingress.
• VAPID keys — Generate once per instance and keep stable. Changing them invalidates existing push subscriptions.