SPB Git

Repository Public

README.md 9.8 KB

# 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

text
 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 with pg_isready.
  • 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.
  • 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.
  • backup (profile tools): runs scripts/backup.sh on demand.
  • .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.

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

  1. Fill in .env at the project root as described in docs/DEPLOYMENT.md §5. For Compose, two things differ:

    • 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;
    • the values of DATABASE_URL, STORAGE_ROOT, BACKUP_DIR, SETUP_URL_FILE and INTERNAL_URL in .env are ignored (overridden).

    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.

  2. Build and start, from the project root:

    bash
    docker compose --env-file .env -f infra/docker-compose.yml up -d --build
    docker compose --env-file .env -f infra/docker-compose.yml ps
  3. Read the one-time enrolment link (valid 24 hours) and open it on the device that will hold the passkey, through the HTTPS origin:

    bash
    docker compose --env-file .env -f infra/docker-compose.yml exec web cat /data/setup/setup-url.txt
  4. Optional demonstration content:

    bash
    docker compose --env-file .env -f infra/docker-compose.yml exec web node_modules/.bin/tsx scripts/seed.ts
  5. Put the reverse proxy in front (Caddyfile.example or nginx.conf.example).

Recovery link, later (needs a terminal: note the -it):

bash
docker compose --env-file .env -f infra/docker-compose.yml exec -it web node_modules/.bin/tsx scripts/setup-token.ts --recovery

Logs: docker compose … logs -f web worker.

# Backups

bash
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 cron

Archives 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:

bash
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

bash
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 --build

The 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:

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. 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.
  7. 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.
  8. 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.
  9. 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.
  10. 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.
  11. Health check of the worker imports postgres from /app/node_modules; it assumes the file stays at /app/infra/healthcheck-worker.mjs.
  12. 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.

# 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.

Files main
Menu

Theme