docs(guides): add Immich guide#2254
Draft
desimone wants to merge 2 commits into
Draft
Conversation
Self-hosted photo library behind Pomerium at the front-door authorization tier. Includes dual Zero/Core tabs, runnable docker-compose + config with byte-identical .yaml.md mirrors, a request-flow diagram, and sealed E2E validation fixtures. AI-assisted (Claude Opus); human-reviewed and validated.
✅ Deploy Preview for pomerium-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
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.
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.
Immich is a self-hosted photo and video library, the thing people run to get off Google Photos. This guide puts its web UI 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 Immich keeps its own accounts underneath. It is the front-door authorization pattern: Pomerium adds a verified-identity gate and an audit trail in front of the app instead of replacing the app's login.
The detail that matters most is that Immich's mobile and desktop apps never touch a browser. They authenticate to the Immich API with their own access tokens and cannot complete an interactive SSO redirect, so gating the whole host would lock every phone out of its own photos. The guide is explicit about routing the web UI through the gate while leaving the app's API path reachable, which keeps that surface behind Immich's own token auth rather than the Pomerium gate, and it points at Immich's native OIDC support as the next step for teams that want one identity everywhere, since the app can run that flow itself. Original-quality uploads and downloads are long plain-HTTP transfers, so the example raises the route's total request timeout independently of WebSocket support to keep a large sync from being cut off mid-transfer.
What ships is a runnable docker-compose (Pomerium, the Immich server, its required VectorChord Postgres image, and Valkey), a matching 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 immich.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 identity and timeout claims against Immich's documentation, 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.