Skip to content

ADR-0029: Demo environment on a single host with Docker Compose

  • Status: Accepted
  • Date: 2026-11-15

Stakeholders need to use the product in a browser, on public addresses, before the production infrastructure exists. The production topology of the Deployment view is still Proposed: no hosting provider is chosen, and no managed database, CDN or release pipeline is provisioned.

The code already builds container images for the API, the worker and the careers server, and every other front end builds to static files. What is missing is a place that runs them together on the six public addresses of ochema.app.

How is a public demo environment run now, without deciding the production infrastructure first?

  • Available in days, with no account or contract that production would have to inherit.
  • The same images and the same production configuration of the code (NODE_ENV=production), so the demo exercises what production will run.
  • No real person can be reached from it: no email, text message or calendar event leaves the environment.
  • No source code and no credential of the code repository on the machine that serves the public.
  • A version can be published and taken back with one command.
  1. One host running the whole stack with Docker Compose, behind a Caddy proxy that issues its own certificates.
  2. Managed services now: a managed PostgreSQL, a managed object storage and a CDN for the static front ends, as in the Proposed production topology.
  3. An application platform that runs containers from a repository and offers a database as an add-on. Common market alternative, listed for comparison.

Chosen option: 1.

The demo environment runs on one host. deploy/docker-compose.prod.yml defines the services: proxy (Caddy, with the static builds of the office system, the driver app, the landing site and the documentation in the same image), api, worker, careers, postgres, redis, s3 (RustFS) and backup, plus tools for the one-off commands of a deploy. Only proxy publishes ports. deploy/Caddyfile maps the six addresses, gets one certificate per address from a public certificate authority, and adds X-Robots-Tag: noindex to every response.

scripts/deploy.sh builds the images away from the host, sends them with docker save and docker load, and drives the host through deploy/remote.sh. The secrets are generated on the host on the first deploy and never leave it. The deploy ends only when GET /health of the public API answers the commit that was built. scripts/deploy.sh rollback brings back the version published before. Email and text messages stay in the simulators, and no calendar provider is connected.

Option 2 was set aside because it means choosing the production provider, its region and its accounts under time pressure, for an environment that holds no real data. Option 3 was set aside because it builds from the repository, so the platform holds a credential of the repository and the source code, and because it ties the demo to a vendor that production may not use.

  • Good, because the demo runs the same images and the same production settings that a production environment will run, and a local copy of the stack (DEPLOY_HOST=local) is tested before each publication.
  • Good, because nothing in it binds the production decision: the Proposed topology stays open.
  • Bad, because there is no high availability. One host serves everything, and a failure of the host takes the whole demo down.
  • Bad, because there is no monitoring and no alerting. A failure is seen when someone opens the product or runs scripts/deploy.sh status.
  • Bad, because the daily copy of the database stays on the same disk as the database. It protects from a failed migration or deleted data, not from losing the host, and the files of the object storage have no copy.
  • Bad, because the deploy is manual, run with scripts/deploy.sh from a machine of the team. No pipeline publishes, and a deploy restarts the API, the worker and the careers server for a few seconds.
  • Bad, because the environment is public and has had no security review. That is why it holds only fictitious data, created by the demo seed, and runs only the simulators of email, SMS and calendar. A real customer’s data never goes there.
  • deploy/docker-compose.prod.yml: the services, their settings and volumes.
  • deploy/Caddyfile: the addresses, the certificates, the static files and the headers.
  • scripts/deploy.sh and deploy/remote.sh: build, publication, rollback, demo seed and status.
  • deploy/backup.sh: the daily copy of the database.
  • Dockerfile: the targets api, worker, careers, proxy and tools.
  • System page: Deployment view.
  • Related records: ADR-0017, ADR-0020.