Deployment overview

Hatch is a Postgres and one API image, and that image also serves every app. compose.yaml at the repository root runs both on one computer, and it is the default: everything on this page is about that file. A cluster is the other way to run it (Kubernetes), and no manifests ship with Hatch.

What runs#

migrate and api are the same image. Because migrate is a separate service, a schema change is applied before the new API is started rather than raced by it, on every start and not only the first. A stack whose migrate shows Exited (0) is a healthy stack.

Two volumes hold what outlives the containers. pgdata (hatch-local_pgdata) is the data: the board, the comments, the keys. workspace holds the container runner's clones and is not data; nothing in it cannot be cloned again. The line name: hatch-local at the top of compose.yaml fixes the project, the network and the volume names, so they are the same wherever the command is run from.

Starting it#

docker compose up -d

Then open <your-hatch-origin>/apps/hatch/, which on one computer is http://localhost:8080/apps/hatch/.

Port 8080 is only the default. HATCH_PORT moves it:

macOS / Linux:

HATCH_PORT=9090 docker compose up -d

PowerShell:

$env:HATCH_PORT=9090; docker compose up -d

Or put a HATCH_PORT=9090 line in the .env beside compose.yaml, which Compose reads on its own, and the port stays moved on every later command.

A profile is named on each command, because Compose starts nothing under a profile nobody named:

docker compose --profile runner up -d

Building it or pulling it#

Compose builds every image from the checkout: db, migrate, api and runner each have a build: and pull_policy: build, so every up rebuilds them. That is why git pull and then up -d is an upgrade (upgrading). The build is all cache when nothing changed.

The same images are also published. .github/workflows/publish.yml pushes them to the GitHub container registry after every green build of the trunk:

<owner> is the account the repository lives under. migrate and api are both hatch-api.

To run from the images instead of building, put a compose.override.yaml beside compose.yaml. Compose reads it on its own and lays it over the file, so nothing in compose.yaml is edited:

services:
  db:
    image: ghcr.io/<owner>/hatch-db:latest
    pull_policy: always
  migrate:
    image: ghcr.io/<owner>/hatch-api:latest
    pull_policy: always
  api:
    image: ghcr.io/<owner>/hatch-api:latest
    pull_policy: always
  runner:
    image: ghcr.io/<owner>/hatch-runner:latest
    pull_policy: always

Leave out runner if you do not use it. Then fetch the images and start them:

docker compose pull
docker compose up -d

A sha tag pins a version; latest follows the trunk. If the packages are private, docker login ghcr.io first, with a token that can read packages.

The variables#

compose.yaml is set from the shell or from a .env beside it, and Environment variables has every one. The operator's eight: HATCH_PORT; HATCH_AUTH → Auth__Enabled; the three HATCH_GOOGLE_* variables → Auth__Google__*; HATCH_PUBLIC_URL → Apps__PublicBaseUrl; and the two HATCH_ANDROID_* variables → Apps__AssetLinks__0__…. The runner's own variables are on the container runner. api passes the shell's own USERNAME/USER as Auth__LocalPerson__Name, so there is nothing to set for that one.

Where secrets go#

• The .env beside compose.yaml. Git-ignored (.gitignore:13-17).
• src/Hatch.Api/.env.json. Bind-mounted at /App/.env.json (compose.yaml:80) and git-ignored (.gitignore:12). It loads after the environment, so it wins (Program.cs:56-62). It holds ha_host, ha_port and ha_token, imported once into site settings (Services/DeviceMapping/DeviceMappingSeeder.cs:131-146), and vm_log_shipper_token (Controllers/VmConsoleLogsController.cs:29). A board needs none of them.
• Never the repository, a commit, an issue or a plan (docs/ethos.md).
• In a cluster, a Secret: see Kubernetes.

What the API reads#

Each key below is the environment spelling (__ per level) of an appsettings.json section. Defaults are the initialisers; the only hosts named anywhere here are localhost, db and compose's own service names.

Auth__SignInPath cannot usefully move: the wall exempts the literal /apps/auth (Services/Auth/AuthGate.cs:180), so pointing it elsewhere opens a redirect loop. The wall's own off/on/required states are covered on the wall, off, on and required.

A malformed Apps__AssetLinks entry stops the API at start (Modules/AssetLinksValidation.cs), unlike Apps__PublicBaseUrl, which degrades quietly.

The migration creates hatch's schema on every start; see backup, restore and replication for backing it up, restoring it and running it on a replica.

How to stop#

docker compose down

down keeps your data. The containers go; the volume outlives them, so down and then up -d again — even after an upgrade has rebuilt the images — brings back the same board. down takes the runner container with it whether or not you name its profile, because it removes everything in the project.

docker compose down -v

down -v throws your data away. The -v removes the volume, and there is no undo. Use it when you want to start over from an empty board, and not otherwise.