pal-e-docs

Review: Enable Keycloak auth in dev environment (docker-compose + terraform redirect URI)

review-1383-2026-06-07 Review

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

  • [x] Type — Feature
  • [x] Lineage — references #159
  • [x] Repo — ldraney/landscaping-assistant
  • [x] User Story — well-formed
  • [x] Context — thorough, explains network path and current state
  • [x] File Targets — present with modify/create and do-not-touch sections
  • [x] Feature Flag — "none" with rationale (correct for infra work)
  • [x] Acceptance Criteria — 7 criteria
  • [x] Test Expectations — present with run command
  • [x] Constraints — present
  • [x] Checklist — present
  • [x] Related — present

Traceability

  • [x] story:auth label — "Auth" user story
  • [x] story note verified — found in project-landscaping-assistant user-stories section (key: "auth", role: "All roles", summary: "Log in with Keycloak, see role-appropriate tabs and features")
  • [ ] arch:rails-app note MISSING — [SCOPE] Create architecture note arch-rails-app for component rails-app
  • [ ] arch:platform note MISSING — [SCOPE] Create architecture note arch-platform for component platform
  • [x] Forgejo issue — #164, open

File Targets

  • [x] docker-compose.yml — verified: exists, currently has no Keycloak env vars in the web service. Adding them is straightforward.
  • [ ] .env.example — does NOT exist yet (ticket says "create"), confirmed. Pattern is valid — /.env* is already in .gitignore.
  • [x] app/controllers/application_controller.rb — verified: contains graceful degradation logic at line 67 (ENV["KEYCLOAK_URL"].present?). Ticket correctly says not to touch.
  • [x] config/initializers/omniauth.rb — verified: contains all 4 Keycloak env var checks (KEYCLOAK_URL, KEYCLOAK_REALM, KEYCLOAK_CLIENT_ID, KEYCLOAK_CLIENT_SECRET). No changes needed here.
  • [x] Cross-repo: pal-e-services/terraform/k3s.tfvars — verified exists locally. Currently has only prod redirect URI: https://landscaping-assistant.tail5b443a.ts.net/auth/keycloak/callback. Dev URI needs to be added.
  • [x] Cross-repo: pal-e-services/terraform/k3s.tfvars.example — verified exists.

Repo Placement

This ticket touches TWO repos: ldraney/landscaping-assistant (docker-compose + .env.example) and pal-e-services (terraform). The issue is filed on landscaping-assistant but explicitly documents the cross-repo work. The checklist calls for separate PRs per repo. This is correctly scoped — no additional Forgejo issues needed since the pal-e-services change is trivial (one line addition to redirect_uris array).

Dependencies

  • Board item #1337 "Phase 1: Keycloak login for single user" — DONE. This ticket builds on that completed work.
  • Board item #1354 (issue #130, phase:2) — DONE. Role-based auth is already working in prod.
  • Board item #1373 (issue #157, phase:2) — in QA. No blocking dependency but related auth work.
  • No blocking dependencies identified. This ticket can proceed independently.

Acceptance Criteria

7 acceptance criteria. All are verifiable by an agent or manual testing:
  • AC1-4: Manual verification via browser (login flow). Agent can verify docker-compose config is correct.
  • AC5: Agent-verifiable by checking the graceful degradation code path.
  • AC6: Agent-verifiable by checking .gitignore (already confirmed: /.env* present).
  • AC7: Requires terraform apply on infra host — human step, correctly documented in checklist.
Criteria are clear and testable. No missing criteria detected.

Blast Radius

Low risk. The docker-compose change only adds environment variables that are already consumed by the existing OmniAuth initializer. The terraform change adds a redirect URI to an existing client — no disruption to prod. The .env file is gitignored so no secret leak risk. Existing test suite (227 specs) should pass unchanged since tests mock KEYCLOAK_URL.

Decomposition Assessment

2 file targets in this repo + 2 file targets in pal-e-services = 4 files across 2 repos. 7 acceptance criteria. However, the actual code changes are minimal (adding env vars to docker-compose, creating a 4-line .env.example, adding one redirect URI to terraform). Estimated agent work: ~3 minutes. No decomposition needed — but the cross-repo nature means two separate PRs as the ticket already specifies.

Recommendations

  • [SCOPE] Create architecture note arch-rails-app for the Rails application component
  • [SCOPE] Create architecture note arch-platform for the platform/infrastructure component
  • [BODY] The docker-compose.yml currently has no env_file directive. The ticket should specify adding env_file: .env to the web service (otherwise the .env file won't be read by docker-compose automatically — docker-compose does auto-read .env for variable substitution in the compose file itself, but NOT for container environment variables unless env_file is specified or variables are listed under environment). Clarify: will the agent add individual environment entries referencing ${KEYCLOAK_URL} etc., or add an env_file: .env directive?