Write the deployment guide and an example reverse proxy config #89

New Issue

2026-08-09T03:51:01+02:00

clawbot commented

2026-08-09 03:51:01 +02:00

Verified against main at 61f42e6. Covers the "documentation: deployment guide" and "example nginx or caddy reverse proxy config" items in TODO.md; confirmed missing — grep finds no nginx or caddy content anywhere in the repo, and README.md covers deployment only via make docker plus a bare docker run (lines 21-23).

Several things already in the code only make sense with a reverse proxy in front, and none of them are written down:

Session cookies are set Secure (#47), so the login UI does not work over plain HTTP — an operator following the current README's docker run -p 8080:8080 and browsing to http://localhost:8080 will find login silently failing to persist. This is the single most likely first-run failure and it is undocumented.
Client IP determination for rate limiting depends on trusted-proxy handling (see the rate-limiting issue).
/metrics is credential-gated but an operator may prefer to gate it at the proxy instead.
state_dir needs a persistent volume; a container without one silently starts with a cold cache on every restart.

Definition of done

A deployment section in README.md (or a docs/deployment.md linked from it) covering: required volumes and their permissions, the TLS requirement for the login UI, state_dir sizing guidance relative to cache_max_bytes (once #51 lands), health check endpoint usage for load balancers, and graceful shutdown/signal behavior.
A working example config for at least one of nginx or caddy, committed in the repo, covering TLS termination, appropriate proxy timeouts for large image fetches, and forwarding the headers pixa needs. Caddy is the smaller example; nginx is the more commonly requested. One is sufficient — say which and why.
A note on what pixa expects to be in front of it versus what it handles itself, so the security boundary is explicit.
Prerequisites for running outside Docker (libvips) documented, since it is the one non-obvious runtime dependency.
make fmt run and formatted output committed; make check green.

Coordination

Worth writing after #51 (cache sizing guidance needs cache_max_bytes to exist) and after the rate-limiting issue (trusted-proxy configuration). Also feeds directly into #17, the uPaaS deployment — that issue is the first consumer of this guide.

Process note

Docs-only if it stays confined to markdown plus an example config file, in which case it skips adversarial review per repo policy.

Verified against `main` at `61f42e6`. Covers the "documentation: deployment guide" and "example nginx or caddy reverse proxy config" items in `TODO.md`; confirmed missing — `grep` finds no nginx or caddy content anywhere in the repo, and `README.md` covers deployment only via `make docker` plus a bare `docker run` (lines 21-23). Several things already in the code only make sense with a reverse proxy in front, and none of them are written down: - Session cookies are set `Secure` (#47), so the login UI **does not work over plain HTTP** — an operator following the current README's `docker run -p 8080:8080` and browsing to `http://localhost:8080` will find login silently failing to persist. This is the single most likely first-run failure and it is undocumented. - Client IP determination for rate limiting depends on trusted-proxy handling (see the rate-limiting issue). - `/metrics` is credential-gated but an operator may prefer to gate it at the proxy instead. - `state_dir` needs a persistent volume; a container without one silently starts with a cold cache on every restart. ## Definition of done 1. A deployment section in `README.md` (or a `docs/deployment.md` linked from it) covering: required volumes and their permissions, the TLS requirement for the login UI, `state_dir` sizing guidance relative to `cache_max_bytes` (once #51 lands), health check endpoint usage for load balancers, and graceful shutdown/signal behavior. 2. A working example config for at least one of nginx or caddy, committed in the repo, covering TLS termination, appropriate proxy timeouts for large image fetches, and forwarding the headers pixa needs. Caddy is the smaller example; nginx is the more commonly requested. One is sufficient — say which and why. 3. A note on what pixa expects to be in front of it versus what it handles itself, so the security boundary is explicit. 4. Prerequisites for running outside Docker (libvips) documented, since it is the one non-obvious runtime dependency. 5. `make fmt` run and formatted output committed; `make check` green. ## Coordination Worth writing **after** #51 (cache sizing guidance needs `cache_max_bytes` to exist) and after the rate-limiting issue (trusted-proxy configuration). Also feeds directly into #17, the uPaaS deployment — that issue is the first consumer of this guide. ## Process note Docs-only if it stays confined to markdown plus an example config file, in which case it skips adversarial review per repo policy.

clawbot added this to the 1.0.0 milestone 2026-08-09 03:51:01 +02:00

clawbot referenced this issue

2026-08-09 16:10:39 +02:00

Tracking: 1.0.0 sequencing and critical path #103

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: sneak/pixa#89