Skip to content

Docker and Compose Boundaries

The repository's Docker Compose profiles are for local development, evaluation, demos, and single-host testing. Start with Getting Started: Docker for the working commands.

What the profiles provide

Profile Purpose Production status
single One API container with bundled PostgreSQL and Redis Evaluation only
ha Two API containers behind Nginx on one host Multi-instance behavior test; not high availability

The ha profile shows load balancing and shared state on one Docker host. Nginx, PostgreSQL, Redis, storage, and the two application containers share that host. A host failure can stop all these components. The profile uses plain HTTP and exposes services for development. Each application container runs the image's database migrations before application startup.

Why it is not a production reference

The checked-in Compose stack does not establish:

  • independent host or zone failure domains;
  • externally managed, authenticated, TLS-protected PostgreSQL and Redis;
  • one coordinated migration workflow before application rollout;
  • immutable signed image digests;
  • TLS and private operational endpoints;
  • non-root/read-only container hardening;
  • automated backup/restore verification;
  • controlled rolling deployment and rollback; or
  • deployment-wide capacity and alert ownership.

Do not copy the Compose file, add restart: always, and label the result production-ready.

Safe evaluation setup

Generate unique secrets and keep them in an uncommitted .env file:

python3 -c 'import secrets; print("DELTALLM_MASTER_KEY=sk-" + secrets.token_hex(20) + "A1")'
python3 -c 'import secrets; print("DELTALLM_SALT_KEY=" + secrets.token_hex(32))'
docker compose --profile single up -d --build

Verify only the process probe from the host:

curl http://localhost:4002/health/liveliness

Detailed health and /metrics are unauthenticated in the application. Keep the evaluation stack on a trusted machine and do not bind it directly to an untrusted network.

Using the image outside Compose

The image command is python -m src.server. It uses migration_mode: startup for single-container evaluation, then runs the managed one-process server. Production runs the exact-image migration stage once and sets migration_mode: external; retain the managed command for early signal drain. Use the process lifecycle contract and provide at least 90 seconds of container stop grace for the initial profile.

See Database migrations, the production checklist, and Kubernetes for the supported operational shape.

Single-host acceptance

If you intentionally operate DeltaLLM on one host, document that availability is limited to that host and independently provide:

  • a TLS reverse proxy;
  • firewall rules that expose only intended application paths;
  • remote encrypted PostgreSQL and object-storage backups;
  • Redis authentication and network restriction;
  • process supervision and disk monitoring; and
  • an exercised restore and upgrade procedure.

That can be an acceptable small installation, but it remains a single failure domain rather than an HA deployment.