Skip to content

Deployment view

This page maps the containers to the places they run. It is section 8 of the arc42 template.

There are two environments today: development, on the machine of each developer, and the demo environment at ochema.app, on a single host with Docker Compose, with fictitious data only. No staging or production environment exists. The production topology at the end of this page is Proposed: it is the target the code is prepared for, and nothing of it is provisioned.

Everything runs on one machine. Three backing services run in containers, and the applications run as Node.js processes straight from the repository.

flowchart TB
  dev(["<b>Developer</b><br/>[Person]"])

  subgraph machine["Developer machine"]
    subgraph fronts["Dev servers, started by pnpm dev"]
      web["<b>Office system</b><br/>[Vite]<br/>port 5173"]
      driver["<b>Driver app</b><br/>[Vite]<br/>port 5174"]
      landing["<b>Landing site</b><br/>[Astro]<br/>port 4321"]
      careers["<b>Careers site</b><br/>[Astro]<br/>port 4322"]
      docs["<b>Docs site</b><br/>[Astro]<br/>port 4323"]
    end

    subgraph back["Node.js processes, started by pnpm dev"]
      api["<b>API</b><br/>[Node.js]<br/>port 3000"]
      worker["<b>Worker</b><br/>[Node.js]<br/>no port"]
    end

    subgraph compose["Docker Compose, loopback ports only"]
      db[("<b>postgres</b><br/>[PostgreSQL 18,<br/>PostGIS]<br/>port 5432")]
      redis[("<b>redis</b><br/>[Redis]<br/>port 6379")]
      s3[("<b>s3</b><br/>[RustFS,<br/>S3-compatible]<br/>port 9000")]
    end

    outbox["<b>Outbox folder</b><br/>[Local files]"]
  end

  dev -->|"Browser"| fronts
  web --> api
  driver --> api
  landing --> api
  careers --> api
  api --> db
  api --> redis
  api --> s3
  worker --> db
  worker --> redis
  worker --> s3
  worker -->|"One file<br/>per email"| outbox

Legend. Rounded shape: a person. Plain box: a process or a folder. Cylinder: a backing service in a container. Nested boxes: where it runs. Arrow: the direction of the call; the developer opens every dev server in a browser. Ports are the defaults of .env.example; every one has a variable.

Terminal window
pnpm install
cp .env.example .env
docker compose up -d # postgres, redis, s3
pnpm --filter @ochema/db db:reset # roles, extensions, every migration
pnpm --filter @ochema/db seed # sample companies and users
pnpm dev # every app, in watch mode
Piece What runs Default port Variable
API apps/api, compiled by tsc --watch and restarted by node --watch. Serves an OpenAPI page at /docs outside production. 3000 API_PORT
Worker apps/worker, started the same way. Creates the local bucket when it is missing. No port None
Office system Vite dev server 5173 WEB_PORT
Driver app Vite dev server 5174 DRIVER_PORT
Landing site Astro dev server 4321 LANDING_PORT
Careers site Astro dev server 4322 CAREERS_PORT
Documentation site Astro dev server 4323, under /docs/ DOCS_PORT
postgres Image postgis/postgis:18-3.7, named volume 5432 POSTGRES_PORT
redis Image redis:8.8.4-alpine, append-only file on, named volume 6379 REDIS_PORT
s3 Image rustfs/rustfs:1.0.5, named volume. S3 API and a web console. 9000, console on 9001 S3_PORT, S3_CONSOLE_PORT

Sources: docker-compose.yml, .env.example, the dev script of each package.json.

  • No outside provider. The defaults are SMS_PROVIDER=simulator, EMAIL_PROVIDER=outbox and MAIL_TRANSPORT=outbox. A text message is kept and logged by the worker; an email becomes a file in the outbox folder. See Context and scope.
  • A database tuned for speed, not safety. The postgres service starts with fsync, synchronous_commit and full_page_writes off and wal_level=minimal, because the test suites create and drop databases all the time. A crash of the machine can corrupt the local databases, which are then rebuilt with the two @ochema/db commands above. These settings must never reach production.
  • Three database roles with login, each with its own connection string: ochema_app for the API and the worker (subject to row level security), ochema_owner for migrations, and the superuser of the container for local tooling only (role bootstrap, reset, seeds, test setup). The applications never use the superuser.
  • Separate databases for tests. The suites of packages/db and apps/api, the volume seed and the end-to-end tests each use their own database on the same server (DATABASE_TEST_NAME, DATABASE_API_TEST_NAME, DATABASE_VOLUME_NAME, E2E_DATABASE_NAME). The end-to-end stack also uses its own ports and its own Redis key prefix, so it runs next to pnpm dev.
  • One configuration file. Every process reads the .env at the root of the repository. It is ignored by git; .env.example is the versioned list of settings, with local values only.

The demo environment lets people use the product on public addresses before the production infrastructure exists. It runs the production images with NODE_ENV=production, on one host, with Docker Compose. Why it is built this way, and what it costs: ADR-0029.

flowchart TB
  people(["<b>Stakeholders</b><br/>[Person]"])

  subgraph host["Demo host, Docker Compose"]
    proxy["<b>proxy</b><br/>[Caddy]<br/>ports 80 and 443<br/>TLS, static front ends"]
    api["<b>api</b><br/>[Container image: api]"]
    careers["<b>careers</b><br/>[Container image: careers]"]
    worker["<b>worker</b><br/>[Container image: worker]"]
    db[("<b>postgres</b><br/>[PostgreSQL 18,<br/>PostGIS]")]
    redis[("<b>redis</b><br/>[Redis]")]
    s3[("<b>s3</b><br/>[RustFS,<br/>S3-compatible]")]
    backup["<b>backup</b><br/>[pg_dump, daily]"]
    outbox["<b>Outbox volume</b><br/>[Local files]"]
  end

  people -->|"HTTPS,<br/>six addresses"| proxy
  proxy -->|"api.*"| api
  proxy -->|"careers.*"| careers
  careers -->|"Project network"| api
  api --> db
  api --> redis
  api --> s3
  worker --> db
  worker --> redis
  worker --> s3
  worker -->|"One file<br/>per email"| outbox
  backup --> db

Legend. Same notation as above. The large box is the host; every box inside it is a service of deploy/docker-compose.prod.yml. Only proxy receives connections from outside. The browsers of the office system, the driver app and the landing site call the API through proxy at api.ochema.app; the careers server calls it inside the project network. The tools service, which runs only during a deploy, is left out.

Address What it serves Served by
ochema.app Landing site, with this documentation under /docs proxy, static files
www.ochema.app A permanent redirect to ochema.app proxy
app.ochema.app Office system (apps/web), with the platform panel under /admin proxy, static files
api.ochema.app API proxy, forwarded to api
careers.ochema.app Careers site (apps/careers), rendered on the server proxy, forwarded to careers
driver.ochema.app Driver app (apps/driver) proxy, static files

Caddy gets one certificate per address from a public certificate authority, answering the challenge on ports 80 and 443 of the host. There is no wildcard certificate and no DNS credential. The public addresses are built into the front end bundles, so an image serves only the domain it was built for. Sources: deploy/Caddyfile, the build-static stage of Dockerfile.

Service Image Published port What it does
proxy ochema/proxy (Caddy) 80 and 443 Ends TLS, serves the static builds of the office system, the driver app, the landing site and the documentation from the same image, forwards api and careers.
api ochema/api None The API.
worker ochema/worker None Queues and scheduled work. Writes every email to the outbox volume.
careers ochema/careers None The careers site.
postgres postgis/postgis:18-3.7 None The database, with the durable settings of PostgreSQL (none of the speed settings of development).
redis redis:8.8.4-alpine None Queues and request counters, with a password and the append-only file on.
s3 rustfs/rustfs:1.0.5 None S3-compatible file storage, without the web console.
backup postgis/postgis:18-3.7 None A pg_dump of the database every day, kept on the host (the 7 newest), and one more before each deploy (the 3 newest).
tools ochema/tools None Only during a deploy: the role bootstrap, the migrations and the demo seed of packages/db.

Only proxy publishes ports. The database, Redis and the file storage are reached by the other containers through the network of the Compose project, and by nothing else. Sources: deploy/docker-compose.prod.yml, deploy/backup.sh.

The secrets are created on the host itself, on the first deploy, as random values in an environment file that only the administrator of the host can read: the passwords of the three database roles and of Redis, the keys of the file storage, SECRETS_ENCRYPTION_KEY and the passwords of the demo seed. The file never leaves the host, and the deploy prints only the names of the variables it added. Later deploys reuse the file and only add a variable that is missing. No development value of .env.example applies there, and the development seed refuses to run with NODE_ENV=production. Source: deploy/remote.sh.

scripts/deploy.sh, run from a machine of the team, publishes the current commit and refuses to run with uncommitted changes.

  1. It builds the five images (api, worker, careers, proxy, tools) away from the host, named after the commit, and sends them with docker save and docker load. The host has no source code, no node_modules, no build cache and no credential of the code repository: only the images, the Compose file and the environment file.
  2. On the host, it copies the database, runs the role bootstrap and the migrations, and starts every service, waiting until each one is healthy. The previous version stays up while the migrations run.
  3. It reads GET https://api.ochema.app/health on the public address. The answer carries the field commit, from the build argument APP_COMMIT, and the deploy succeeds only when it equals the commit that was built.

scripts/deploy.sh rollback starts the version published before and swaps the two, so a second rollback undoes the first. The host keeps only the current and the previous version. A rollback does not touch the database: the migrations of the newer version stay applied. Sources: scripts/deploy.sh, deploy/remote.sh, apps/api/src/modules/platform/health/health.controller.ts.

  • A banner on the office system, the driver app and the careers site: “Demo environment. Test data only. Emails and text messages are simulated and not delivered.” It is on when the front ends are built with VITE_DEMO_NOTICE or PUBLIC_DEMO_NOTICE set, which the deploy does by default.
  • X-Robots-Tag: noindex on every response of proxy, so search engines do not index the demo. The automatic redirect from HTTP to HTTPS, which Caddy answers before the rules of each address, does not carry it.

Nothing leaves the host. The configuration sets MAIL_TRANSPORT=outbox and EMAIL_PROVIDER=outbox, so every email becomes a JSON file in the outbox volume of the worker, and SMS_PROVIDER=simulator, so every text message stays in the simulator. No OAuth application of a calendar provider is configured, and CALENDAR_ADAPTERS=fake is refused in production, so no calendar can be connected. See Context and scope.

It is not the production topology below, which the architecture of the product sets as the target: a managed PostgreSQL, a managed S3 bucket and the static front ends on a CDN. The demo environment has none of that:

  • One host, with no redundancy: a failure of the host stops every address.
  • No monitoring and no alerting.
  • The copies of the database stay on the same disk as the database, and the files of the storage have no copy.
  • No pipeline: every deploy is run by hand with scripts/deploy.sh, and it restarts the API, the worker and the careers server for a few seconds.
flowchart TB
  people(["<b>Carrier staff, applicants,<br/>drivers, visitors</b><br/>[Person]"])

  subgraph static["Static hosting behind a CDN (Proposed)"]
    web["<b>Office system</b><br/>[Static files]"]
    driver["<b>Driver app</b><br/>[Static files]"]
    landing["<b>Landing and docs sites</b><br/>[Static files]<br/>ochema.app, ochema.app/docs"]
  end

  subgraph run["Container runtime behind a TLS proxy (Proposed)"]
    careers["<b>Careers site</b><br/>[Container image: careers]<br/>careers.ochema.app"]
    api["<b>API</b><br/>[Container image: api]"]
    worker["<b>Worker</b><br/>[Container image: worker]"]
  end

  subgraph managed["Managed services (Proposed)"]
    db[("<b>Database</b><br/>[Managed PostgreSQL, PostGIS]")]
    redis[("<b>Queues and counters</b><br/>[Redis]")]
    storage[("<b>File storage</b><br/>[Managed S3, private bucket]")]
  end

  providers[["<b>SMS, email and<br/>calendar providers</b><br/>[External systems]"]]

  people --> web
  people --> driver
  people --> landing
  people --> careers
  web -->|"HTTPS"| api
  driver -->|"HTTPS"| api
  landing -->|"HTTPS"| api
  careers -->|"Private address"| api
  api --> db
  api --> redis
  api --> storage
  worker --> db
  worker --> redis
  worker --> storage
  worker --> providers
  api <-->|"Webhooks in,<br/>OAuth out"| providers

Legend. Same notation as above. Every grouping box is Proposed. The arrows between the API, the worker and the providers are the ones of the container diagram in Building blocks: the worker sends and syncs, the providers call the API back through webhooks, and the API calls a provider for the OAuth flow of a calendar. The two host names shown are the ones the code already uses as defaults; the addresses of the office system, the driver app and the API are not decided.

Fact Where
Three container images, built from one Dockerfile with the targets api, worker and careers. Each runs as the non-root user node, contains only production dependencies, and stops cleanly on SIGTERM. Dockerfile
Health checks in the images: GET /health on the API checks the database, Redis and the audit log partitions; GET /health on the careers server. Dockerfile, apps/api/src/modules/platform/health
The other front ends build to static files (vite build, astro build). The landing build output carries the documentation under /docs. apps/web, apps/driver, apps/landing, turbo.json
No serverless functions. The API, the worker and the careers server are long-running processes. Dockerfile
The file storage adapter speaks the S3 API and uses the default credential chain of the AWS SDK when no key is configured. The worker creates a bucket only outside production. apps/api/src/core/storage, apps/worker/src/main.ts
Every transaction sets its company context as its first statement and returns the connection clean, which is compatible with a connection pooler in transaction mode. packages/db/src/context.ts
The continuous integration workflow builds the three images to check them. It pushes nothing. .github/workflows/ci.yml

All of these are enforced by the code, in apps/api/src/core/config/config.ts, apps/api/src/app.ts and the messaging and calendar modules.

  • With NODE_ENV=production, the test routes of the messaging simulator are not registered, CALENDAR_ADAPTERS=fake is refused, the OpenAPI page of the API is not served, and with SMTP the upgrade to TLS is mandatory.
  • With an https address in API_URL, the session cookies are named with the __Host- prefix and are always Secure, and the API sends HSTS.
  • With a real provider selected (SMS_PROVIDER=twilio, EMAIL_PROVIDER=smtp or ses), the API and the worker refuse to start when a setting of that provider is missing, and the error names the variable.

Settings a production environment must decide

Section titled “Settings a production environment must decide”
Setting Why it matters
CORS_ORIGINS The list of front end origins the API accepts, also used by the cross-site request check.
TRUST_PROXY_HOPS, CAREERS_TRUST_PROXY_HOPS The number of proxies in front of the API and of the careers server. Request limits and the proof of an electronic signature record the address of the visitor only when every hop is counted, the careers server included.
PUBLIC_API_BASE_URL The address of the API as a provider reaches it. Webhook addresses are built from it, and webhook signatures are checked against it.
CAREERS_URL, CAREERS_API_URL The public origin of the careers site, used in every link sent to a candidate, and the address the careers server reaches the API on.
SECRETS_ENCRYPTION_KEY The key of the sensitive personal data, of the calendar secrets and of the email reply addresses. Without it, the routes that write or reveal sensitive data answer 503. Replacing the key is a requirement of its own, in Quality requirements.
DATABASE_URL, DATABASE_MIGRATION_URL Two roles: the runtime role and the owner that runs migrations. Migrations are applied with pnpm --filter @ochema/db migrate before the new version starts.
S3_* A private bucket, provisioned outside the application.

These parts of a production environment have no code or configuration in the repository yet: the choice of hosting, infrastructure as code, a release pipeline, backup and restore procedures for managed services, monitoring and alerting, and sizing. The demo environment has a manual deploy and a daily copy of the database local to its host, which are not a production answer to any of them. Running more than one instance of the API or of the worker is Not verified: sessions live in the database and request counters in Redis, which the design intends for several instances, but no test runs that way.

  • ADR-0006: worker, queues and work discovery by company.
  • ADR-0008: Astro for the public sites.
  • ADR-0017: S3-compatible file storage.
  • ADR-0020: documentation with Starlight at /docs.
  • ADR-0029: demo environment on a single host with Docker Compose.
  • Quality requirements: availability, scale and operation, with their state.