infra/ — Docker Compose alternative and reverse-proxy examples
Status: written, not run
The files in this directory were written by reading the code. They have not been built, started or tested by their author. No Docker build was run, no container was started, no proxy configuration was loaded. Treat them as a careful first draft: expect to fix something on first use, and check the list of unverified points below.
The owner's production installation does not use these files. It runs the two processes under PM2 through his own orchestrator, behind an existing Caddy gateway reached over WireGuard. This directory is for someone who wants a generic self-hosted install.
| File | Purpose |
|---|---|
Dockerfile |
One image for the web process, the worker and the backup job: Node, pnpm, dependencies, Chromium headless shell for exports, PostgreSQL 17 client tools for backups, the production build |
Dockerfile.dockerignore |
Ignore list for the build context (the project root); keeps .env, node_modules, .next and .git out of the image |
docker-compose.yml |
Services web, worker, postgres (+ an on-demand backup), networks, volumes, health checks |
healthcheck-worker.mjs |
Health check of the worker container (reads the heartbeat row) |
Caddyfile.example |
Reverse-proxy block for Caddy 2 |
nginx.conf.example |
Reverse-proxy block for nginx |
What the Compose file sets up
host: reverse proxy (TLS) ──▶ 127.0.0.1:8700
│
┌──────────────▼──────────────┐
network "edge" │ web worker │──▶ Internet (Anthropic, Crossref, doi.org, source URLs)
└──────┬───────────┬──────────┘
network "db" │ │ (internal: no route out, nothing published)
(internal) ┌──────▼───────────▼──────────┐
│ postgres │
└─────────────────────────────┘
volumes: pgdata (database) · storage (uploads, exports; shared by web and worker)
backups (encrypted archives) · setup (the one-time enrolment link)postgres:postgres:17, user and database created from environment variables, attached to the internal network only, no published port, health check withpg_isready.web: builds the image; at each start runsscripts/migrate.ts,scripts/bootstrap.ts, thenserver.ts. Published on127.0.0.1:8700only. Health check:GET /api/health.worker: same image, runssrc/worker/index.ts, starts afterwebis healthy, shares thestoragevolume, openshttp://web:8700/render/…for exports. One replica. Health check: heartbeat younger than 60 s.backup(profiletools): runsscripts/backup.shon demand..envis passed withenv_file; the Compose file overrides the variables whose value differs inside containers (DATABASE_URL,STORAGE_ROOT,BACKUP_DIR,SETUP_URL_FILE,INTERNAL_URL,HOST,PORT) and emptiesCHROMIUM_PATHso that the browser installed in the image is used.
The reverse proxy and TLS are not in the Compose file. Run Caddy or nginx on the host (or add your own service) in front of 127.0.0.1:8700.
Use
-
Fill in
.envat the project root as described indocs/DEPLOYMENT.md§5. For Compose, two things differ:- add a line
POSTGRES_PASSWORD=<long random, URL-safe: letters and digits>— the Compose file buildsDATABASE_URLfrom it and gives it to PostgreSQL; - the values of
DATABASE_URL,STORAGE_ROOT,BACKUP_DIR,SETUP_URL_FILEandINTERNAL_URLin.envare ignored (overridden).
APP_URLmust be the final public origin (WebAuthn compares it). It is read at run time; changing it needs a restart, not a rebuild — but it invalidates enrolled passkeys unlessWEBAUTHN_RP_IDkeeps the old host. - add a line
-
Build and start, from the project root:
bashdocker compose --env-file .env -f infra/docker-compose.yml up -d --build docker compose --env-file .env -f infra/docker-compose.yml ps -
Read the one-time enrolment link (valid 24 hours) and open it on the device that will hold the passkey, through the HTTPS origin:
bashdocker compose --env-file .env -f infra/docker-compose.yml exec web cat /data/setup/setup-url.txt -
Optional demonstration content:
bashdocker compose --env-file .env -f infra/docker-compose.yml exec web node_modules/.bin/tsx scripts/seed.ts -
Put the reverse proxy in front (
Caddyfile.exampleornginx.conf.example).
Recovery link, later (needs a terminal: note the -it):
docker compose --env-file .env -f infra/docker-compose.yml exec -it web node_modules/.bin/tsx scripts/setup-token.ts --recoveryLogs: docker compose … logs -f web worker.
Backups
openssl rand -base64 48 > infra/backup-passphrase && chmod 600 infra/backup-passphrase # once; keep a copy elsewhere
docker compose --env-file .env -f infra/docker-compose.yml run --rm backup # schedule this with host cronArchives land in the backups volume, each with a .hmac file that restore.sh checks. Copy both off the host; that is not automated. Restore with the same image:
docker compose --env-file .env -f infra/docker-compose.yml run --rm backup \
bash scripts/restore.sh db /data/backups/db/<file>.dump.enc postgres://sheet_app:<password>@postgres:5432/<empty database>See docs/BACKUP_RESTORE.md for what the scripts do.
Upgrade
docker compose --env-file .env -f infra/docker-compose.yml run --rm backup
git pull
docker compose --env-file .env -f infra/docker-compose.yml up -d --buildThe web container applies new migrations when it starts. Rolling back means checking out the previous revision and rebuilding; across a migration, restore the backup (docs/DEPLOYMENT.md §16).
Unverified points
Things most likely to need attention on first use, with the reasoning behind each choice:
- Base image tag.
node:26-bookworm-slimmatches the Node version the project is developed on. If that tag does not exist in your registry, setNODE_VERSIONto a version the dependencies accept. - pnpm. Installed with
npm install -g pnpm@11.pnpm-workspace.yamllists the packages allowed to run build scripts for both pnpm 11 and 12; an install that stops on a build-script prompt means that list needs the new package. - Chromium. The image installs
chromium-headless-shellwith--with-depsinto/ms-playwright(PLAYWRIGHT_BROWSERS_PATH), andCHROMIUM_PATHis left empty so Playwright picks that build. The worker launches the browser once at start-up and reports the result (worker.chromium_missingin its log, the heartbeat on the dashboard): look there first if exports fail. - Chromium sandbox in a container. Playwright starts Chromium without its sandbox by default, which is what lets it run as the unprivileged
nodeuser here. The worker only ever loads the application's own/renderpage and aborts every other request.shm_size: 1gbis set for the worker; if captures crash, look there first. - PostgreSQL client from PGDG.
backup.shneedspg_dump17; Debian bookworm ships 15. The Dockerfile adds the PGDG repository. That step needs network access toapt.postgresql.orgat build time. - Build-time environment.
next buildruns with a placeholderDATABASE_URL(modules read it at import; no connection is opened). Nothing else is needed at build time as far as the code shows (robots.txtis rendered per request); if the build fails on a missing variable, add it to thatRUNline. - Secret file permissions. The
backupservice runs as usernode(uid 1000) and reads the passphrase from/run/secrets/backup_passphrase, which is a bind mount ofinfra/backup-passphrasewith its host permissions. If the host file is 0600 and owned by a different uid, the container cannot read it; make the owner uid 1000 or relax the mode. Whetherdocker compose up(without thetoolsprofile) complains when that file does not exist yet depends on the Compose version; create the file first if it does. - Volume ownership. The image creates
/data/storage,/data/backupsand/data/setupowned bynode; named volumes inherit that on first use. Bind mounts instead of named volumes must be writable by uid 1000. env_fileparsing. Docker readsKEY=valuelines; quotes and inline comments are handled differently from the application's own loader (scripts/_env.ts). Keep.envto plainKEY=valuelines.- Client addresses. The application takes the last
X-Forwarded-Forvalue. With the port published on127.0.0.1and one proxy on the host, that is the address the proxy saw. If you publish the port on another interface, clients can reach the application directly and supply their own header. Whether Docker's port forwarding leaves the proxy's connection untouched (it should for loopback) has not been checked. - Health check of the worker imports
postgresfrom/app/node_modules; it assumes the file stays at/app/infra/healthcheck-worker.mjs. - Proxy examples. Directive names were written from memory of Caddy 2 and current nginx (
http2 on;needs nginx ≥ 1.25.1; on older versions uselisten 443 ssl http2;). Validate withcaddy validate/nginx -tbefore reloading.
Why Compose is only an alternative
The application is two Node processes and a database; it does not need containers. The Compose files exist so that a generic install has a reproducible starting point, and they are honest about not having been exercised. If you run them and fix something, update this README: replace "not run" with what you ran and when.