I set up Pomerium Core successfully with Claude Code by pointing it to pomerium.com. After everything was set up. I asked it, "document any issues you had that weren't straightforward in the docs and let me know what they were so I can improve the docs". This was the feedback, so I think we could make some improvements.
Here's what I ran into:
- Installation docs were hard to find
Every URL I tried returned 404:
- pomerium.com/docs/core/install
- pomerium.com/docs/core
- pomerium.com/docs/deploy
- pomerium.com/docs (landing page didn't surface install links clearly enough for automated extraction)
I ended up relying on prior knowledge (GitHub releases API + Docker image at cr.pomerium.com/pomerium/pomerium) rather than the docs. A
canonical /docs/install or prominent "Get Started" link on the docs landing page would help.
- Hosted authenticate service docs not discoverable
I tried pomerium.com/docs/capabilities/hosted-authenticate-service — also 404. I knew from prior knowledge that it's just
authenticate_service_url: https://authenticate.pomerium.app, but someone without that context would struggle to find the config key and
value.
- Docker image registry not documented prominently
The image is at cr.pomerium.com/pomerium/pomerium — not Docker Hub. This is a common stumbling point. If someone tries docker pull
pomerium/pomerium they won't get the latest. The registry should be called out clearly in install/quickstart docs.
- Verify image location
Similarly, cr.pomerium.com/pomerium/verify isn't obvious. A quickstart that includes a working docker-compose with the verify service
would be a great "hello world" for new users.
- autocert_use_staging — good that it exists, easy to find
This one was fine — the config reference made it clear. No issues there.
TL;DR — the two biggest gaps are: doc URL structure / discoverability, and the hosted authenticate service setup not having a clear
dedicated page. A single "Quickstart with Docker + Hosted Auth" page covering image registry, minimal config, and a verify route would
eliminate most of what I hit.
I set up Pomerium Core successfully with Claude Code by pointing it to pomerium.com. After everything was set up. I asked it, "document any issues you had that weren't straightforward in the docs and let me know what they were so I can improve the docs". This was the feedback, so I think we could make some improvements.
Here's what I ran into:
Every URL I tried returned 404:
I ended up relying on prior knowledge (GitHub releases API + Docker image at cr.pomerium.com/pomerium/pomerium) rather than the docs. A
canonical /docs/install or prominent "Get Started" link on the docs landing page would help.
I tried pomerium.com/docs/capabilities/hosted-authenticate-service — also 404. I knew from prior knowledge that it's just
authenticate_service_url: https://authenticate.pomerium.app, but someone without that context would struggle to find the config key and
value.
The image is at cr.pomerium.com/pomerium/pomerium — not Docker Hub. This is a common stumbling point. If someone tries docker pull
pomerium/pomerium they won't get the latest. The registry should be called out clearly in install/quickstart docs.
Similarly, cr.pomerium.com/pomerium/verify isn't obvious. A quickstart that includes a working docker-compose with the verify service
would be a great "hello world" for new users.
This one was fine — the config reference made it clear. No issues there.
TL;DR — the two biggest gaps are: doc URL structure / discoverability, and the hosted authenticate service setup not having a clear
dedicated page. A single "Quickstart with Docker + Hosted Auth" page covering image registry, minimal config, and a verify route would
eliminate most of what I hit.