Skip to main content

​
Prerequisites

  • Docker Engine 24 or later with Compose v2
  • Node.js 22 or later, to generate secrets
  • at least 2 vCPU, 4 GB of RAM, and durable disk storage
  • a public DNS name for the dashboard
  • Twilio and OpenAI accounts for live calls, and a Twilio Elastic SIP trunk for phone calls

​
Configure the environment

The script copies .env.example to .env and fills every PostgreSQL role password and internal secret with a random 64-character value. It won’t overwrite an existing .env unless you pass --force, which also replaces every secret in it. Then open .env and set APP_BASE_URL, OPENAI_API_KEY, and your Twilio credentials. Services build their database connection strings from the role passwords, so you don’t need to write any database URLs. Compose sets STORAGE_PROVIDER=local by default. The admin and worker mount the same persistent storage_data volume at /var/lib/lobbystack/storage.
Do not expose a stack that still uses the example passwords or change-me secrets.

​
Start LobbyStack

The migrator applies PostgreSQL migrations before the admin and worker services start. Health checks hold dependent services until their prerequisites are ready. The admin readiness response includes PostgreSQL, Redis, and storage checks. The worker readiness response includes PostgreSQL, Redis, and storage status. LobbyStack does not run monitoring containers. Application logs remain available through docker compose logs, and the health endpoints continue to work.

​
Choose a storage backend

The default local provider supports a single Docker host. Back up the storage_data volume with PostgreSQL and restore both from the same recovery point. Use S3 when the admin and worker run on different hosts. Set these values in .env:
AWS workloads may omit the access-key variables when the container can use an AWS credential role. MinIO remains available through a Compose profile. Configure the S3 variables for MinIO, then start the stack with the profile:
For local email inspection, start Mailpit:

​
Export OpenTelemetry data

OpenTelemetry export is disabled when OTEL_EXPORTER_OTLP_ENDPOINT is empty. To send traces, metrics, and OpenTelemetry logs to PostHog, add these values to .env:
Use your regional PostHog host and project token. LobbyStack appends /v1/traces, /v1/metrics, and /v1/logs to the base URL. You can use the same variables with another OTLP-compatible backend. Restart the application containers after changing the values:
Direct product analytics and error reporting use their own PostHog configuration.

​
Verify the deployment

The default service ports bind to localhost. Put public traffic through Caddy or another trusted reverse proxy.

​
Production checklist

  • replace all development credentials and limit .env permissions
  • use a production HTTPS value for APP_BASE_URL
  • set OPENAI_WEBHOOK_SECRET and TWILIO_SIP_TRUNK_SID to answer phone calls. The worker won’t provision a phone number without TWILIO_SIP_TRUNK_SID. The voice calls variables list what each one does
  • set WEB_CALL_ALLOWED_ORIGINS to the exact sites that host your public demo call, if you run one
  • configure off-host PostgreSQL and file-storage backups
  • run a restore drill before accepting production traffic
  • restrict PostgreSQL, Redis, and optional MinIO ports to private networks
  • monitor admin, worker, queue, database, and object-storage health
  • pin image versions before planned upgrades

​
Upgrades

Back up PostgreSQL and the configured storage backend before upgrading. Review new migrations and environment variables before restarting services.