sneak/pixa
1
0
Fork 0
Code Issues 11 Pull Requests 4 Actions 11 Packages Projects Releases Wiki Activity

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

New Issue
Closed
opened 2026-08-09 03:51:01 +02:00 by clawbot · 2 comments
clawbot commented 2026-08-09 03:51:01 +02:00
Collaborator
Copy Link
Copy Source

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.

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 commented 2026-10-04 13:00:16 +02:00
Author
Collaborator
Copy Link
Copy Source

Plan, checked against next at c7173c4. Since this issue was filed, README.md gained "Running under upaas" (port, volume, environment, health check), the HTTPS requirement of the login and generator pages, the trusted_proxies advice and every route's status codes. What is still missing, and what this unit adds:

  • README.md, a "Deployment" section next to "Running under upaas", short and linking to what is already written rather than repeating it:
    • what pixa expects in front of it: a reverse proxy that terminates TLS, passes Host and Referer through unchanged, sets X-Forwarded-For (with trusted_proxies set to the address pixa sees it from), and whose timeouts are at least downstream_timeout; /metrics may also be closed at the proxy;
    • what pixa does itself: signature and encrypted-URL checks, the allowlist, refusing private and local upstream addresses, the login rate limit, the size limits and the security headers;
    • the state directory needs a persistent volume (without one every restart starts with an empty cache), sized for cache_max_bytes as the code defines it;
    • the health check for a load balancer, and what a stop does (SIGTERM, how long it waits, the exit codes), as the code does it today;
    • running outside Docker: libvips (the version the Dockerfile installs) and a C compiler for CGO.
  • One example config: a Caddyfile, because it is the smallest correct one (Caddy gets certificates itself, keeps Host and sets X-Forwarded-For by default). Put it where REPO_POLICIES.md allows such a file (or under docs/ if it says nothing), and say where in the PR. Check it once with caddy validate in a container; do not add a check script.
  • Documentation only. Markdown wrapped by hand until #100 makes make fmt format it.

Model: opus-5-5

Plan, checked against `next` at `c7173c4`. Since this issue was filed, `README.md` gained "Running under upaas" (port, volume, environment, health check), the HTTPS requirement of the login and generator pages, the `trusted_proxies` advice and every route's status codes. What is still missing, and what this unit adds: - `README.md`, a "Deployment" section next to "Running under upaas", short and linking to what is already written rather than repeating it: - what pixa expects in front of it: a reverse proxy that terminates TLS, passes `Host` and `Referer` through unchanged, sets `X-Forwarded-For` (with `trusted_proxies` set to the address pixa sees it from), and whose timeouts are at least `downstream_timeout`; `/metrics` may also be closed at the proxy; - what pixa does itself: signature and encrypted-URL checks, the allowlist, refusing private and local upstream addresses, the login rate limit, the size limits and the security headers; - the state directory needs a persistent volume (without one every restart starts with an empty cache), sized for `cache_max_bytes` as the code defines it; - the health check for a load balancer, and what a stop does (SIGTERM, how long it waits, the exit codes), as the code does it today; - running outside Docker: libvips (the version the `Dockerfile` installs) and a C compiler for CGO. - One example config: a Caddyfile, because it is the smallest correct one (Caddy gets certificates itself, keeps `Host` and sets `X-Forwarded-For` by default). Put it where `REPO_POLICIES.md` allows such a file (or under `docs/` if it says nothing), and say where in the PR. Check it once with `caddy validate` in a container; do not add a check script. - Documentation only. Markdown wrapped by hand until https://git.eeqj.de/sneak/pixa/issues/100 makes `make fmt` format it. Model: opus-5-5
clawbot commented 2026-10-04 13:39:47 +02:00
Author
Collaborator
Copy Link
Copy Source

Done in #182: a "Deployment" section in README.md and the example configs/Caddyfile, per the plan above.

Model: opus-5-5

Done in https://git.eeqj.de/sneak/pixa/pulls/182: a "Deployment" section in `README.md` and the example `configs/Caddyfile`, per the plan above. Model: opus-5-5
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
critical
Extremely important: data loss, a security hole, production down, or basic use impossible
 merge-ready
needs-checks
needs-rebase
needs-review
needs-rework
No labels
Milestone
No items
No Milestone 1.0.0
Projects
Clear projects
No projects
Assignees
Clear assignees
clawbot sneak (Jeffrey Paul)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: sneak/pixa#89