Docker Deployment¶

Quick Start¶

Prerequisites: Docker 20.10+, Compose 2.0+, 4 GB RAM, 10 GB disk

First-time build:

docker compose build

Run:

./docker-start.sh                    # Interactive (prompts for API key)
# OR
cp .env.example .env && docker-compose up -d  # Edit .env first

CPU mode is the default for direct Compose runs. ./docker-start.sh auto-adds docker-compose.gpu.yml only when a working NVIDIA runtime is detected.

# Force CPU
docker compose -f docker-compose.yml -f docker-compose.cpu.yml up -d

# Opt into NVIDIA GPU
docker compose -f docker-compose.yml -f docker-compose.gpu.yml up -d

The default image uses native Python on both Intel/AMD and ARM hosts, including Apple Silicon, and does not require NVIDIA libraries. For SynPlanner on Linux x86_64, build with INSTALL_RETROSYNTHESIS=true docker compose build chainlit-app.

For CUDA PyTorch on DGX Spark / Linux ARM64, explicitly build the NGC profile:

BASE_IMAGE=nvcr.io/nvidia/pytorch:25.11-py3 USE_SYSTEM_TORCH=true docker compose build
docker compose -f docker-compose.yml -f docker-compose.gpu.yml up -d

This GPU profile reuses the NGC image's Torch packages and is separate from the locked native CPU installation. The retrosynthesis extra currently requires Linux x86_64 (see the installation guide).

Access: App | MinIO Console (cs_copilot / chempwd123) | PostgreSQL: localhost:5432

Services¶

Service	Purpose	Ports
chainlit-app	Main application	8000
minio	S3-compatible storage	9000, 9001
postgres	Chat history DB	5432
minio-setup	One-time bucket init	-
chainlit-db-init	Prisma migrations	-

The MinIO server and client are built from pinned official source commits in Dockerfile.minio, because the upstream Docker Hub and Quay images could not be pulled during integration. The pins correspond to server RELEASE.2025-10-15T17-29-55Z and client RELEASE.2025-08-13T08-35-41Z. Their source links and licenses remain in the images. First-time builds therefore also require access to GitHub and the Go module registry. See upstream source build instructions.

Secret Management¶

CHAINLIT_AUTH_SECRET is auto-generated on first start and persisted to ./data/.chainlit_secret.

Priority: env var > persisted file > generate new

# Override
CHAINLIT_AUTH_SECRET=your-secret  # in .env

# Regenerate
docker-compose down && rm ./data/.chainlit_secret && docker-compose up -d

# Backup (for production)
cp ./data/.chainlit_secret chainlit_secret_backup.txt

Development¶

# Hot-reload
docker-compose -f docker-compose.yml -f docker-compose.dev.yml up

# Rebuild
docker compose build

# Complete reset
docker compose down -v --remove-orphans --rmi all

# Local storage only (no MinIO)
USE_S3=false  # in .env

Dependencies¶

Uses uv for reproducible builds from uv.lock.

uv sync                              # Update deps on host
docker compose build chainlit-app    # Rebuild image

Common Operations¶

docker-compose ps                    # Status
docker-compose logs -f chainlit-app  # Logs
docker-compose down                  # Stop
docker-compose down -v               # Stop + delete data
docker-compose restart chainlit-app  # Restart
docker-compose exec chainlit-app bash                      # Shell
docker-compose exec postgres psql -U postgres -d chainlit  # DB shell

Troubleshooting¶

Issue	Solution
App won't start	`docker-compose logs chainlit-app`, check `DEEPSEEK_API_KEY`
Port conflict	Use `./docker-start.sh` (auto-detects free ports)
DB error "relation User does not exist"	`docker-compose up -d chainlit-db-init && docker-compose restart chainlit-app`
MinIO issues	`docker-compose logs minio-setup`
`could not select device driver "nvidia"`	Run CPU mode or use `./docker-start.sh`; only use `docker-compose.gpu.yml` on hosts with NVIDIA Container Toolkit
Out of memory	Docker Desktop > Settings > Resources > Memory >= 4 GB
Disk space	`docker system prune`

Production¶

# Strong secrets
CHAINLIT_AUTH_SECRET=$(openssl rand -hex 32)
MINIO_SECRET_KEY=$(openssl rand -base64 32)

# Backup
docker-compose exec postgres pg_dump -U postgres chainlit > backup.sql

# Restore
cat backup.sql | docker-compose exec -T postgres psql -U postgres -d chainlit

Recommendations: HTTPS via nginx/Traefik, don't expose PostgreSQL publicly, restart: always, external PostgreSQL/S3 for scaling.