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.
Development environment
Section titled “Development environment”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.
How it is started
Section titled “How it is started”pnpm installcp .env.example .envdocker compose up -d # postgres, redis, s3pnpm --filter @ochema/db db:reset # roles, extensions, every migrationpnpm --filter @ochema/db seed # sample companies and userspnpm 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.
What is specific to development
Section titled “What is specific to development”- No outside provider. The defaults are
SMS_PROVIDER=simulator,EMAIL_PROVIDER=outboxandMAIL_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
postgresservice starts withfsync,synchronous_commitandfull_page_writesoff andwal_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/dbcommands above. These settings must never reach production. - Three database roles with login, each with its own connection string:
ochema_appfor the API and the worker (subject to row level security),ochema_ownerfor 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/dbandapps/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 topnpm dev. - One configuration file. Every process reads the
.envat the root of the repository. It is ignored by git;.env.exampleis the versioned list of settings, with local values only.
Demo environment
Section titled “Demo environment”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.
Public addresses
Section titled “Public addresses”| 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.
Services
Section titled “Services”| 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.
Secrets
Section titled “Secrets”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.
How a version is published
Section titled “How a version is published”scripts/deploy.sh, run from a machine of the team, publishes the current commit and refuses to run with uncommitted changes.
- It builds the five images (
api,worker,careers,proxy,tools) away from the host, named after the commit, and sends them withdocker saveanddocker load. The host has no source code, nonode_modules, no build cache and no credential of the code repository: only the images, the Compose file and the environment file. - 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.
- It reads
GET https://api.ochema.app/healthon the public address. The answer carries the fieldcommit, from the build argumentAPP_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.
How it is marked as a demo
Section titled “How it is marked as a demo”- 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_NOTICEorPUBLIC_DEMO_NOTICEset, which the deploy does by default. X-Robots-Tag: noindexon every response ofproxy, 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.
Simulators
Section titled “Simulators”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.
What the demo environment is not
Section titled “What the demo environment is not”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.
Production topology (Proposed)
Section titled “Production topology (Proposed)”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.
What the code already provides
Section titled “What the code already provides”| 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 |
What a production configuration changes
Section titled “What a production configuration changes”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=fakeis refused, the OpenAPI page of the API is not served, and with SMTP the upgrade to TLS is mandatory. - With an
httpsaddress inAPI_URL, the session cookies are named with the__Host-prefix and are alwaysSecure, and the API sends HSTS. - With a real provider selected (
SMS_PROVIDER=twilio,EMAIL_PROVIDER=smtporses), 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. |
Planned
Section titled “Planned”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.
Related
Section titled “Related”- 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.