Repository Public
1# infra/ — Docker Compose alternative and reverse-proxy examples23## Status: written, not run45**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.67The 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.89| File | Purpose |10|---|---|11| `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 |12| `Dockerfile.dockerignore` | Ignore list for the build context (the project root); keeps `.env`, `node_modules`, `.next` and `.git` out of the image |13| `docker-compose.yml` | Services `web`, `worker`, `postgres` (+ an on-demand `backup`), networks, volumes, health checks |14| `healthcheck-worker.mjs` | Health check of the worker container (reads the heartbeat row) |15| `Caddyfile.example` | Reverse-proxy block for Caddy 2 |16| `nginx.conf.example` | Reverse-proxy block for nginx |1718## What the Compose file sets up1920```21 host: reverse proxy (TLS) ──▶ 127.0.0.1:870022 │23 ┌──────────────▼──────────────┐24 network "edge" │ web worker │──▶ Internet (Anthropic, Crossref, doi.org, source URLs)25 └──────┬───────────┬──────────┘26 network "db" │ │ (internal: no route out, nothing published)27 (internal) ┌──────▼───────────▼──────────┐28 │ postgres │29 └─────────────────────────────┘3031 volumes: pgdata (database) · storage (uploads, exports; shared by web and worker)32 backups (encrypted archives) · setup (the one-time enrolment link)33```3435- `postgres`: `postgres:17`, user and database created from environment variables, attached to the internal network only, **no published port**, health check with `pg_isready`.36- `web`: builds the image; at each start runs `scripts/migrate.ts`, `scripts/bootstrap.ts`, then `server.ts`. Published on `127.0.0.1:8700` only. Health check: `GET /api/health`.37- `worker`: same image, runs `src/worker/index.ts`, starts after `web` is healthy, shares the `storage` volume, opens `http://web:8700/render/…` for exports. One replica. Health check: heartbeat younger than 60 s.38- `backup` (profile `tools`): runs `scripts/backup.sh` on demand.39- `.env` is passed with `env_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 empties `CHROMIUM_PATH` so that the browser installed in the image is used.4041The 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`.4243## Use44451. Fill in `.env` at the project root as described in `docs/DEPLOYMENT.md` §5. For Compose, two things differ:46 - add a line `POSTGRES_PASSWORD=<long random, URL-safe: letters and digits>` — the Compose file builds `DATABASE_URL` from it and gives it to PostgreSQL;47 - the values of `DATABASE_URL`, `STORAGE_ROOT`, `BACKUP_DIR`, `SETUP_URL_FILE` and `INTERNAL_URL` in `.env` are ignored (overridden).4849 `APP_URL` must 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 unless `WEBAUTHN_RP_ID` keeps the old host.50512. Build and start, from the project root:5253 ```bash54 docker compose --env-file .env -f infra/docker-compose.yml up -d --build55 docker compose --env-file .env -f infra/docker-compose.yml ps56 ```57583. Read the one-time enrolment link (valid 24 hours) and open it on the device that will hold the passkey, through the HTTPS origin:5960 ```bash61 docker compose --env-file .env -f infra/docker-compose.yml exec web cat /data/setup/setup-url.txt62 ```63644. Optional demonstration content:6566 ```bash67 docker compose --env-file .env -f infra/docker-compose.yml exec web node_modules/.bin/tsx scripts/seed.ts68 ```69705. Put the reverse proxy in front (`Caddyfile.example` or `nginx.conf.example`).7172Recovery link, later (needs a terminal: note the `-it`):7374```bash75docker compose --env-file .env -f infra/docker-compose.yml exec -it web node_modules/.bin/tsx scripts/setup-token.ts --recovery76```7778Logs: `docker compose … logs -f web worker`.7980### Backups8182```bash83openssl rand -base64 48 > infra/backup-passphrase && chmod 600 infra/backup-passphrase # once; keep a copy elsewhere84docker compose --env-file .env -f infra/docker-compose.yml run --rm backup # schedule this with host cron85```8687Archives 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:8889```bash90docker compose --env-file .env -f infra/docker-compose.yml run --rm backup \91 bash scripts/restore.sh db /data/backups/db/<file>.dump.enc postgres://sheet_app:<password>@postgres:5432/<empty database>92```9394See `docs/BACKUP_RESTORE.md` for what the scripts do.9596### Upgrade9798```bash99docker compose --env-file .env -f infra/docker-compose.yml run --rm backup100git pull101docker compose --env-file .env -f infra/docker-compose.yml up -d --build102```103104The 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).105106## Unverified points107108Things most likely to need attention on first use, with the reasoning behind each choice:1091101. **Base image tag.** `node:26-bookworm-slim` matches the Node version the project is developed on. If that tag does not exist in your registry, set `NODE_VERSION` to a version the dependencies accept.1112. **pnpm.** Installed with `npm install -g pnpm@11`. `pnpm-workspace.yaml` lists 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.1123. **Chromium.** The image installs `chromium-headless-shell` with `--with-deps` into `/ms-playwright` (`PLAYWRIGHT_BROWSERS_PATH`), and `CHROMIUM_PATH` is left empty so Playwright picks that build. The worker launches the browser once at start-up and reports the result (`worker.chromium_missing` in its log, the heartbeat on the dashboard): look there first if exports fail.1134. **Chromium sandbox in a container.** Playwright starts Chromium without its sandbox by default, which is what lets it run as the unprivileged `node` user here. The worker only ever loads the application's own `/render` page and aborts every other request. `shm_size: 1gb` is set for the worker; if captures crash, look there first.1145. **PostgreSQL client from PGDG.** `backup.sh` needs `pg_dump` 17; Debian bookworm ships 15. The Dockerfile adds the PGDG repository. That step needs network access to `apt.postgresql.org` at build time.1156. **Build-time environment.** `next build` runs with a placeholder `DATABASE_URL` (modules read it at import; no connection is opened). Nothing else is needed at build time as far as the code shows (`robots.txt` is rendered per request); if the build fails on a missing variable, add it to that `RUN` line.1167. **Secret file permissions.** The `backup` service runs as user `node` (uid 1000) and reads the passphrase from `/run/secrets/backup_passphrase`, which is a bind mount of `infra/backup-passphrase` with 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. Whether `docker compose up` (without the `tools` profile) complains when that file does not exist yet depends on the Compose version; create the file first if it does.1178. **Volume ownership.** The image creates `/data/storage`, `/data/backups` and `/data/setup` owned by `node`; named volumes inherit that on first use. Bind mounts instead of named volumes must be writable by uid 1000.1189. **`env_file` parsing.** Docker reads `KEY=value` lines; quotes and inline comments are handled differently from the application's own loader (`scripts/_env.ts`). Keep `.env` to plain `KEY=value` lines.11910. **Client addresses.** The application takes the last `X-Forwarded-For` value. With the port published on `127.0.0.1` and 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.12011. **Health check of the worker** imports `postgres` from `/app/node_modules`; it assumes the file stays at `/app/infra/healthcheck-worker.mjs`.12112. **Proxy examples.** Directive names were written from memory of Caddy 2 and current nginx (`http2 on;` needs nginx ≥ 1.25.1; on older versions use `listen 443 ssl http2;`). Validate with `caddy validate` / `nginx -t` before reloading.122123## Why Compose is only an alternative124125The 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.126