pal-e-docs

Review: Provision staging environment for deploy validation

review-1946-2026-08-01 Review

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

  • [x] Type -- Feature
  • [x] Lineage
  • [x] Repo
  • [x] User Story
  • [x] Context
  • [x] File Targets
  • [x] Feature Flag
  • [x] Acceptance Criteria
  • [x] Test Expectations
  • [x] Constraints
  • [x] Checklist
  • [x] Related
All 12 required sections for a Feature issue are present.

Traceability

  • [x] arch:infra label -- arch-infra note exists (Infrastructure: paldocs (Hetzner Edge, DNS, Traffic Routing)). Covers DNS, Caddy, Tailscale funnel patterns.
  • [x] arch note verified -- arch-infra note exists in pal-e-docs
  • [ ] story:deploy-validation label -- NOT found in project-landscaping-assistant user-stories table. 16 stories listed; none match "deploy-validation". [SCOPE] Create user story entry on project-landscaping-assistant user-stories section.
  • [x] Forgejo issue -- ldraney/landscaping-assistant#342, state: open

File Targets

  • [x] pal-e-services/terraform/k3s.tfvars -- verified: file exists (symlink to secrets). Contains services map (line 327) with landscaping-assistant entry, service_databases map (line 17) with landscaping entry including 4 databases, Keycloak realm/client config (lines 98, 191). ISS staging reference pattern confirmed at lines 34 (databases), 400 (service).
  • [x] pal-e-platform/terraform/dns.tf -- verified: file exists. Contains godaddy_dns_record resources for existing domains. ISS dev uses CNAME (line 64), not A record as ticket states, but functionally equivalent for subdomains. Agent can determine correct record type from pattern.
  • [x] pal-e-deployments/overlays/landscaping-assistant/staging/* -- correctly marked as new files. Parent directory exists with dev/ and prod/. ISS staging reference at overlays/intelligentstaffingsystems/staging/ confirmed with kustomization.yaml, deployment-patch.yaml, secrets.enc.yaml.
  • [ ] pal-e-platform/salt/pillar/caddy.sls -- MISSING from scope. Caddy reverse proxy is managed via Salt pillar data. Each public domain needs a site entry (domain, proxy_target, www_redirect). Without adding staging.landscaping-assistant.app, Caddy on the edge VPS will not proxy traffic to the staging Tailscale funnel. ISS dev reference: iss-dev entry exists at line 37. [BODY] Add file target for Caddy pillar.
  • [ ] landscaping-assistant/config/environments/production.rb -- MISSING from scope. Rails config.hosts (lines 97-99) only allows landscaping-assistant.app, landscaping-assistant.tail5b443a.ts.net, landscaping-dev.tail5b443a.ts.net. The /up health check is excluded from host authorization (line 102-104), so AC "curl /up returns 200" would pass, but all other routes would return 403 without adding staging.landscaping-assistant.app. [BODY] Add file target for Rails config.hosts.

Repo Placement

Issue filed on ldraney/landscaping-assistant as a project-level tracking issue. Actual work spans 3-4 repos. Acceptable pattern for cross-repo infrastructure work.
Issue: Repo section lists forgejo_admin/pal-e-platform but git remote shows ldraney/pal-e-platform. Board items #1463 and #1942 also reference ldraney/pal-e-platform. [BODY] Fix owner to ldraney/pal-e-platform.

Dependencies

  • Item #1945 (backlog): "Add dev.landscaping-assistant.app to Keycloak redirect URIs" -- similar Keycloak/DNS pattern but independent. Not blocking.
  • Item #1940 (qa): "Keycloak login/reset redirects to Tailscale URL instead of public domain" -- could affect staging login, but staging uses a separate Keycloak realm. Not blocking.
  • No critical blocking dependencies found. Dependencies are not documented in the issue scope but none are blocking.

Acceptance Criteria

8 criteria, all agent-testable:
  • AC 1 (staging URL loads): testable via curl after deploy
  • AC 2 (auto-deploy): testable by checking Image Updater annotation in kustomization.yaml
  • AC 3-5 (observability): testable by checking ServiceMonitor, PrometheusRules, blackbox probe manifests. ISS staging overlay includes ServiceMonitor rename patch as reference.
  • AC 6 (prod manual): testable by verifying no Image Updater annotation on prod overlay
  • AC 7-8 (separate DB, separate realm): testable by checking Terraform plan output and Keycloak admin
Test expectations include concrete commands (tofu plan, kubectl kustomize, curl /up). Adequate.
Note: AC 1 ("loads and serves the app") will fail if config.hosts gap is not addressed -- Rails will return 403 for all routes except /up.

Blast Radius

All changes are additive -- new entries in Terraform maps, new overlay directory, new DNS record, new Caddy site entry. Prod overlay explicitly excluded in "Files NOT to touch" section. Low blast radius.
ISS staging is a proven reference pattern already in production.

Decomposition Assessment

NEEDS DECOMPOSITION
  • File targets: 6+ files across 4 repos (pal-e-services, pal-e-platform, pal-e-deployments, landscaping-assistant) -- exceeds 3 files / 2 repos threshold
  • Acceptance criteria: 8 -- exceeds 5 threshold
  • Estimated agent work: >5 minutes (Terraform changes across 2 repos, SOPS encryption, kustomize overlay, DNS record, Caddy pillar, Keycloak realm, Rails config.hosts, 3+ separate PRs)
  • Natural decomposition boundary: one sub-issue per repo/PR
[DECOMPOSE] Route to skill-decompose-ticket. Suggested sub-issues:
  • pal-e-services: Add staging service, databases, Keycloak realm/client to k3s.tfvars
  • pal-e-platform: Add DNS record (dns.tf) + Caddy site entry (salt/pillar/caddy.sls)
  • pal-e-deployments: Create staging overlay (kustomization.yaml, deployment-patch.yaml, secrets.enc.yaml)
  • landscaping-assistant: Add staging.landscaping-assistant.app to Rails config.hosts

Recommendation

  • [SCOPE] Create user story entry "deploy-validation" on project-landscaping-assistant user-stories section.
  • [BODY] Add missing file target: pal-e-platform/salt/pillar/caddy.sls -- add staging site entry (domain: staging.landscaping-assistant.app, proxy_target: landscaping-assistant-staging.tail5b443a.ts.net). Without this, Caddy will not proxy the staging domain.
  • [BODY] Add missing file target: landscaping-assistant/config/environments/production.rb -- add config.hosts << "staging.landscaping-assistant.app". Without this, Rails returns 403 for all non-/up routes.
  • [BODY] Fix Repo section: forgejo_admin/pal-e-platform should be ldraney/pal-e-platform (confirmed via git remote and board item history).
  • [DECOMPOSE] 8 AC across 4 repos with 3+ PRs required. Route to skill-decompose-ticket for automated sub-ticket creation.