Document Keycloak public ingress via auth.palinks.app #36

New issue

Open

opened 2026-06-18 01:05:25 +00:00 by ldraney · 0 comments

ldraney commented

2026-06-18 01:05:25 +00:00

Owner

Type

Feature

Lineage

Standalone — discovered during custom domain wave 3 validation. Keycloak was unreachable from public domains because KC_HOSTNAME was hardcoded to the Tailscale hostname.

Repo

ldraney/godaddy-tofu

User Story

As a platform operator
I want documentation of the Keycloak public ingress architecture
So that future domain onboarding includes the auth endpoint setup

Context

Apps behind custom domains (e.g., landscaping-assistant.app) redirect to Keycloak for login, but KC_HOSTNAME=keycloak.tail5b443a.ts.net made the auth endpoint unreachable for public users. Experimentally verified that removing KC_HOSTNAME and relying on KC_PROXY_HEADERS=xforwarded allows dual-access (public via auth.palinks.app + internal via Tailscale) with correct OIDC URL generation per path.

File Targets

docs/keycloak-public-ingress.md — new doc with Mermaid diagrams covering problem, solution, architecture, and per-repo change list
docs/deployment.md — add auth.palinks.app to flow diagram and target domains table
README.md — add new doc to documentation table

Feature Flag

None

Acceptance Criteria

docs/keycloak-public-ingress.md exists with problem statement, solution, architecture diagrams, and per-repo change list
docs/deployment.md includes auth.palinks.app in the flow diagram and target domains table
README docs table links to the new doc

Test Expectations

Mermaid diagrams render correctly in Forgejo
Cross-check per-repo change list against actual file paths in pal-e-platform and pal-e-services

Constraints

Docs only — no code changes in this repo
Follow existing Mermaid diagram style from docs/deployment.md

Checklist

PR opened
No unrelated changes

godaddy-tofu — this repo's docs

### Type Feature ### Lineage Standalone — discovered during custom domain wave 3 validation. Keycloak was unreachable from public domains because KC_HOSTNAME was hardcoded to the Tailscale hostname. ### Repo `ldraney/godaddy-tofu` ### User Story As a platform operator I want documentation of the Keycloak public ingress architecture So that future domain onboarding includes the auth endpoint setup ### Context Apps behind custom domains (e.g., `landscaping-assistant.app`) redirect to Keycloak for login, but `KC_HOSTNAME=keycloak.tail5b443a.ts.net` made the auth endpoint unreachable for public users. Experimentally verified that removing `KC_HOSTNAME` and relying on `KC_PROXY_HEADERS=xforwarded` allows dual-access (public via `auth.palinks.app` + internal via Tailscale) with correct OIDC URL generation per path. ### File Targets - `docs/keycloak-public-ingress.md` — new doc with Mermaid diagrams covering problem, solution, architecture, and per-repo change list - `docs/deployment.md` — add auth.palinks.app to flow diagram and target domains table - `README.md` — add new doc to documentation table ### Feature Flag None ### Acceptance Criteria - [ ] `docs/keycloak-public-ingress.md` exists with problem statement, solution, architecture diagrams, and per-repo change list - [ ] `docs/deployment.md` includes `auth.palinks.app` in the flow diagram and target domains table - [ ] README docs table links to the new doc ### Test Expectations - [ ] Mermaid diagrams render correctly in Forgejo - [ ] Cross-check per-repo change list against actual file paths in pal-e-platform and pal-e-services ### Constraints - Docs only — no code changes in this repo - Follow existing Mermaid diagram style from `docs/deployment.md` ### Checklist - [ ] PR opened - [ ] No unrelated changes ### Related - `godaddy-tofu` — this repo's docs