docs(guides): add Paperless-ngx guide#2256
Draft
desimone wants to merge 4 commits into
Draft
Conversation
✅ Deploy Preview for pomerium-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Self-hosted document management behind Pomerium at the front-door authorization tier. Dual Zero/Core tabs, runnable docker-compose + config with byte-identical .yaml.md mirrors, request-flow diagram, sealed E2E fixtures. AI-assisted (Claude Opus); human-reviewed and validated.
desimone
force-pushed
the
bdd/guide-paperless-ngx
branch
from
9c254f1 to
30c1817
Compare
Address review feedback: condense duplicated value framing, use canonical Pomerium terms (front door, route, policy, the From URL), replace the client-gating SVG with a markdown table, simplify the mermaid diagram, rewrite double-hyphen and em-dash punctuation per the guide style rules, reorder config sections, and scope prerequisites to what each tab actually needs.
The guide-review style rule now welcomes real em dashes and only bans double-hyphen fakes, so restore the reviewer's verbatim suggestion and the em-dash section headings.
Finish the terminology sweep from the Jellyfin review: replace the remaining 'public route host' / 'public route' / 'public name' phrasings with the route's From URL where the route hostname is meant.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Paperless-ngx is a self-hosted document manager for the sensitive paper you would rather not host on someone else's cloud: tax records, contracts, medical files. This guide puts it behind Pomerium so the browser front door is gated by your existing identity provider with single sign-on, group and domain policy, and MFA, while Paperless keeps its own accounts underneath. Pomerium sits in front as a verified-identity gate and audit trail rather than replacing the app's login.
The gotcha here is that Paperless-ngx is a Django app, and Django validates the incoming
Hostheader againstALLOWED_HOSTS(derived fromPAPERLESS_URL) and runs CSRF checks on top. If the public route host does not matchPAPERLESS_URL, or the route does not preserve the host header, Django answers with an HTTP 400 and nothing else works, so the guide makes that the first thing it gets right. On identity, Paperless is one of the apps in this set that can actually consume a verified identity: it natively supports trusted-header SSO viaPAPERLESS_ENABLE_HTTP_REMOTE_USER, so the guide separates the default front-door gate from that upgrade and shows how to forward Pomerium's verified identity as anX-Pomerium-Claim-*header for direct sign-in, with the necessary caveat that Pomerium must be the only path in and must strip any client-supplied identity header.What ships is a runnable docker-compose (Pomerium, Paperless-ngx, Postgres, and Redis) on an internal-only network so the single way in is through Pomerium, a config with both Pomerium Zero console steps and Pomerium Core
config.yaml, a request-flow diagram, and an access-channel table. The bundledvalidate/directory is the sealed end-to-end harness for the example; with #2251 on main it runs in CI automatically, and it passed a full local run (Keycloak SSO login, live upstream assertions, network-isolation check) viascripts/validate-guide-fixtures.sh paperless-ngx.This is one of four guides split out of the closed #2253 so each app can be reviewed on its own.
AI assistance
Claude Opus drafted the guide prose, the docker-compose and config example, the diagram, and the validation fixtures. I reviewed and edited the content, doc-verified the Django
ALLOWED_HOSTS/CSRF behavior and the trusted-header SSO path against Paperless-ngx's docs, and confirmed the site builds locally (yarn build,cspell,prettier --check). A follow-up cleanup commit (Claude-drafted, applying the review feedback on #2255 across the set) condensed duplicated framing, replaced the gating-matrix SVG with a markdown table, simplified the mermaid diagram, removed em and double-hyphen dashes per the guide style rules, scoped the prerequisites per tab, and fixed reviewer-caught accuracy gaps. I reviewed the cleanup before it was pushed; the local gates and the sealed E2E fixture (yarn build,cspell,format-check,guide-audit,scripts/validate-guide-fixtures.sh) were run by Claude on a merge with current main and passed.