docs(app-router): HTTPS-Secure-cookie requirement + Hermes dashboard build step#129
docs(app-router): HTTPS-Secure-cookie requirement + Hermes dashboard build step#129TechNickAI wants to merge 2 commits into
Conversation
… dashboard build step Two recurring gotchas hit during fleet rollout, now documented: 1. The session cookie is Secure, so password-protected apps only work over HTTPS. Serving over a plain-HTTP Tailscale listener makes login appear to succeed (303) but every subsequent request bounces back to login because the browser never returns the cookie. Added notes to the Auth Model and Troubleshooting sections, plus the HTTPS tailnet-serve command. 2. Hermes dashboards crash-loop under --skip-build when web_dist was never built on a fresh install. Added an 'Adding a Hermes dashboard' subsection covering the one-time 'npm run build', profile/HERMES_HOME pinning, and the X-Forwarded-Prefix Caddy block, plus a matching troubleshooting entry.
Reflow long lines to satisfy the repo's prettier pre-commit hook. No content changes.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 9b3b7c9cb4
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| Tailscale Serve listener (e.g. `tailscale serve --http=<port>`), login will appear to | ||
| succeed (the POST returns a 303) but every subsequent request gets bounced back to the | ||
| login page because the cookie never returns. Always expose the router over an **HTTPS** | ||
| door — `tailscale serve --https=<port> http://127.0.0.1:8080` for tailnet-only, or the |
There was a problem hiding this comment.
On hosts following this README outside Tailscale Services, this replacement command omits --bg; I checked Tailscale's serve CLI reference, which says --bg is what makes tailscale serve run persistently in the background. If an operator uses this command to fix the plain-HTTP cookie loop, it only works for the foreground session and the router stops being exposed when the shell exits, which brings the login bounce back. Either include --bg here or direct users to update tailscale-serve.json and re-apply the launchd-backed config.
Useful? React with 👍 / 👎.
1 participant
What
Documents two recurring gotchas discovered while rolling out Hermes dashboards across several fleet machines with the app-router.
1. Password-protected apps require HTTPS (Secure cookie)
The auth-service session cookie is set with the
Secureattribute, so browsers andcurlrefuse to send it back over plainhttp://. If you front the router with a plain-HTTP Tailscale Serve listener, login appears to succeed (the POST returns 303) but every subsequent request bounces back to the login page because the cookie never returns — a confusing failure that looks like broken auth.Added:
tailscale serve --https=<port>command2. Hermes dashboards need
web_distbuilt firstOn a fresh Hermes install,
hermes dashboard --skip-buildcrash-loops with✗ --skip-build was passed but no web dist foundbecause the SPA was never built.Added:
npm run build, profile/HERMES_HOMEpinning (so PM2's rewritten$HOMEdoesn't point at an empty DB), and theX-Forwarded-PrefixCaddy blockWhy
Both cost real debugging time during rollout. Documenting them so the next machine goes faster.
Scope
Docs only —
devops/app-router/README.md, +62 lines. No code or behavior changes. No PII (placeholders only).