Skip to content

docs: Windows 11 + Coder two-hop port-forward guide, Keycloak sync troubleshooting - #32

Merged
achankra merged 1 commit into
InternalDeveloperPlatform:mainfrom
elserhumano:fernando-windows-doc-1
Aug 6, 2026
Merged

docs: Windows 11 + Coder two-hop port-forward guide, Keycloak sync troubleshooting#32
achankra merged 1 commit into
InternalDeveloperPlatform:mainfrom
elserhumano:fernando-windows-doc-1

Conversation

@elserhumano

Copy link
Copy Markdown
Contributor

Add Windows 11 / Coder two-hop port-forward guide + Keycloak troubleshooting

What

Adds documentation for students on Windows 11 without Coder Connect/Coder Desktop, plus a troubleshooting section covering a Keycloak config issue that caused a blank screen / login failure.

Why

Hit this working through the teams-management workshop on Windows 11 Pro. Coder Connect wouldn't reliably resolve the workspace hostname, so I used a two-hop port-forward pattern (kubectl port-forward in the workspace + coder port-forward in PowerShell) to reach the API, UI, and Keycloak via localhost. Got everything working end-to-end (API + UI + Keycloak login) and wrote up what it took so other Windows students don't hit the same wall.

Changes to README_Teams_Management_UI.md

  • New "Windows 11 + Coder (without Coder Connect)" section: the two-hop port-forward pattern with a port table for all 5 services (API, deployed UI, dev-server UI, Keycloak, Grafana).
  • Troubleshooting: documents the 4 places that need to agree on the access URL for Keycloak login to work (KC_HOSTNAME, realm webOrigins/redirectUris, environment.ts, and keycloak.config.ts — this last one is easy to miss since it's separate from environment.ts and not mentioned elsewhere).
  • Note on angular.json (cli.analytics: false) to stop ng serve from hanging on an interactive prompt in the Coder workspace.

Known bugs flagged (not fixed in this PR, just documented)

  • keycloak.yaml is missing a --- separator between the realm ConfigMap and the second (CORS-enhanced) Deployment block, which breaks kubectl apply.
  • The realm's webOrigins has an unfilled placeholder (http://fernando-pe-arch.coder:<port>).

Happy to open a follow-up PR fixing the YAML bugs directly if useful — let me know.

cc @ajay

@achankra
achankra merged commit 2770b35 into InternalDeveloperPlatform:main Aug 6, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants