Deploy with Docker Compose
Run a released version of OCI with the bundled Compose file, behind your own TLS proxy, with one or several API replicas.
The repository's docker/compose.yaml is the supported deployment. It runs:
| Service | Image | Notes |
|---|---|---|
web | OCI_WEB_IMAGE | Published on OCI_PORT (8080). Forwards /api/* to the API. |
api | OCI_API_IMAGE | Applies migrations on start unless RUN_MIGRATIONS=false. Files on the storage_data volume. |
migrate | OCI_API_IMAGE | Profile tools. A one-shot migration job for multi-replica rollouts. |
postgres | postgres:17-alpine | Volume postgres_data. |
redis | redis:7-alpine | Volume redis_data. |
minio | minio/minio | Profile s3. Optional S3-compatible storage. |
searxng | searxng/searxng | Profile search. Optional web search. |
Install
Get the Compose file
git clone https://github.com/ncecere/open-chat-interface.git
cd open-chat-interface
git checkout v0.10.2
cd dockerConfigure
Create docker/.env (or supply the variables from your secret manager):
APP_URL=https://chat.example.edu
POSTGRES_PASSWORD=<openssl rand -hex 24>
AUTH_SECRET=<openssl rand -base64 48>
ENCRYPTION_KEY=<openssl rand -base64 48>
INITIAL_ADMIN_EMAIL=morgan.lee@example.edu
# Leave INITIAL_ADMIN_PASSWORD out to get a one-time password in the API's log.
# Behind a load balancer or another proxy: its addresses (see Reverse proxy).
# TRUSTED_PROXIES=10.0.0.0/8
OCI_API_IMAGE=ghcr.io/ncecere/open-chat-interface/api:v0.10.2
OCI_WEB_IMAGE=ghcr.io/ncecere/open-chat-interface/web:v0.10.2APP_URL must be the address people use, through your proxy. See Configuration for everything else. Without INITIAL_ADMIN_PASSWORD, the API prints a one-time password for the first administrator to its log (docker compose logs api) the first time it starts; a password you do set must be at least 12 characters. Unset variables are left out of the containers, and an empty optional variable counts as unset.
Start
docker compose pull api web
docker compose up -d --no-build
docker compose ps
curl --fail "http://localhost:${OCI_PORT:-8080}/api/health/ready"Without OCI_API_IMAGE and OCI_WEB_IMAGE, Compose builds the images from the checkout instead. For a released deployment, keep both set and always start with --no-build.
Put a TLS proxy in front
Point your reverse proxy or load balancer at the web container's port, and set TRUSTED_PROXIES to its addresses so the audit log, sessions and the sign-in limit see each person's own address. See Reverse proxy.
Pin versions
Pin both images to the same vX.Y.Z. Use latest only for evaluation: it moves with each release, and its two images are updated one after the other, not together. For content identity independent of tags, pin by digest. Released images are linux/amd64 only.
The images are public, so pulling them needs no registry login.
More than one API replica
Startup migrations are guarded by a PostgreSQL advisory lock, so replicas can start together. For a predictable rollout, run migrations as their own step:
docker compose --profile tools run --rm migrate
RUN_MIGRATIONS=false docker compose up -d --no-build --scale api=3A replica started with RUN_MIGRATIONS=false against a database missing the latest migration refuses to start. The web container's Caddy re-resolves the api service name every ten seconds, so new replicas are found as you scale, and it retries a failed replica. No sticky sessions are needed: sessions are cookies and replies are resumed through Redis.
Before scaling:
- Use S3-compatible storage. The local driver writes to a per-container volume, so a file uploaded through one replica is invisible to the others.
- Use Redis. Without it, rate limits and reply recovery are per replica.
- Role and ban changes lag. Sessions are cached for up to five minutes per replica.
- Database connections: each replica needs its pool plus one connection per running background job.
Optional services
docker compose --profile search up -dadds SearXNG, reachable from the API athttp://searxng:8080. Enable JSON output in its settings, then configure it under Web search.docker compose --profile s3 up -dadds MinIO. SetMINIO_USERandMINIO_PASSWORD, create a bucket, then configure Storage. For production, prefer a managed or properly operated S3 service.
Day to day
| Task | Command |
|---|---|
| Logs | docker compose logs -f api |
| Status | docker compose ps |
| Promote an account to admin | docker compose exec api node dist/scripts/promote-admin.js someone@example.edu |
| Database shell | docker compose exec postgres psql --username=oci --dbname=oci |
Upgrades: Upgrades. Backups: Backups and restore.