pal-e-docs

Review: Deploy paldocs to production

review-1369-2026-06-06 Review

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Re-review (2026-06-06) after refinement attempt. The issue body was updated but key findings from the first review remain unaddressed.

Prior Findings Status

Prior Finding Status
[BODY] AC #6 db:migrate incorrect NOT FIXED -- issue still says "db:migrate runs on pod startup via entrypoint (PR #21 wired this)"
[BODY] ArgoCD Application location unclear NOT ADDRESSED
[BODY] harbor-creds pattern unclear PARTIALLY -- checklist item added to investigate, acceptable for ops ticket
[SCOPE] story-paldocs-infra missing NOT CREATED
[SCOPE] arch-ci-cd missing NOT CREATED
[SCOPE] sop-secrets-management reference PARTIALLY -- changed to service-onboarding-sop, which also does not exist
[DECOMPOSE] 7 AC across 3 repos Repo scope reduced from 3 to 2. See decomposition assessment below.

Template Completeness

  • [x] Type -- Feature
  • [x] Lineage -- references #15 CI/CD and #14 infra spike
  • [x] Repo -- ldraney/paldocs (primary), ldraney/pal-e-deployments
  • [x] User Story -- present as narrative
  • [x] Context -- thorough, includes what exists and what's missing
  • [x] File Targets -- 5 resources listed with actions (table format, clear)
  • [x] Acceptance Criteria -- 8 criteria listed (1 is factually incorrect)
  • [x] Test Expectations -- present
  • [x] Constraints -- 4 constraints documented
  • [x] Checklist -- 9 items
  • [x] Related -- references to issues and SOPs
All required sections for a Feature template are present.

Traceability

  • [x] story:infra label -- present on board item
  • [ ] story note MISSING -- No story-paldocs-infra note exists in pal-e-docs. The project-paldocs user-stories section only lists story-paldocs-kanban and story-paldocs-project-pages. Infrastructure/deployment work is foundational -- acceptable to defer, but the note should still be created. [SCOPE] Create user story entry story-paldocs-infra on project-paldocs user-stories section.
  • [x] arch:ci-cd label -- present on board item
  • [ ] arch note MISSING -- No arch-ci-cd note exists in pal-e-docs. Search returned zero results. [SCOPE] Create architecture note arch-ci-cd for CI/CD component.
  • [x] Forgejo issue -- ldraney/paldocs#22, state: open

File Targets

  • [x] paldocs namespace -- Create. No namespace exists yet. Kustomization at pal-e-deployments/overlays/paldocs/prod/kustomization.yaml sets namespace: paldocs. Must be created before ArgoCD Application (per CreateNamespace=false constraint). Correctly documented.
  • [x] paldocs-secrets Secret -- Create. Deployment patch references paldocs-secrets with keys SECRET_KEY_BASE and DATABASE_URL. The env var mapping is correct: secret key DATABASE_URL maps to env var PALDOCS_DATABASE_URL, which matches config/database.yml production config.
  • [x] harbor-creds Secret -- Create. The base deployment template references harbor-creds imagePullSecrets. Issue now includes a checklist step to investigate the provisioning pattern from landscaping-assistant. Acceptable for an ops ticket.
  • [x] ArgoCD Application -- Create. Reference pattern from landscaping-assistant is included in the issue body with full YAML. Clear enough for execution.
  • [x] Tailscale Ingress -- Create. Production URL target documented.

Repo Placement

Improved from first review. Issue now lists 2 repos instead of 3 (removed pal-e-platform). The issue is filed on ldraney/paldocs which is the service being deployed. Actual work is primarily cluster-level kubectl operations plus potentially an ArgoCD Application manifest in pal-e-deployments. Placement is acceptable for a deployment ticket.

Dependencies

  • #15 (CI/CD infrastructure) -- DONE. Board item #1359 is in done column. Pipeline builds images and updates kustomize tags. Verified: .woodpecker.yaml has build-and-push + update-kustomize-tag steps.
  • #14 (Infra spike) -- DONE. Board item #1345 is in done column.
  • pal-e-deployments PR #179 -- Merged. Overlay files exist.
  • Terraform DB secret -- exists as paledocs-db-url in pal-e-app namespace.
  • No blocking items found on the board. This ticket has no upstream blockers.

Acceptance Criteria

  • [x] kubectl get ns paldocs -- verifiable
  • [x] kubectl get secret paldocs-secrets -n paldocs -- verifiable
  • [x] kubectl get secret harbor-creds -n paldocs -- verifiable (new AC, addresses harbor-creds gap)
  • [x] kubectl get application paldocs -n argocd -- verifiable
  • [x] Pod running + /up health check -- verifiable
  • [ ] AC #6 STILL INCORRECT: "db:migrate runs on pod startup via entrypoint (PR #21 wired this)" -- The bin/docker-entrypoint explicitly skips db:prepare with comment: "Shared database -- Rails does not manage migrations. Skip db:prepare; tables already exist (managed by pal-e-docs FastAPI)." The entrypoint just calls exec "${@}". This AC must be removed or reworded. [BODY] Replace AC #6 with: "Entrypoint starts cleanly without migration errors (shared DB, Python-managed schema)."
  • [x] Production URL resolves -- verifiable
  • [x] CI merge triggers full pipeline -- verifiable end-to-end

Blast Radius

  • Shared database: The paledocs database is shared between pal-e-docs (FastAPI, Python-managed schema) and this Rails app (read + triggers). The DATABASE_URL secret must use the same credentials. Correctly documented in constraints.
  • harbor-creds pattern: Cross-cutting concern for namespace provisioning. Adequately flagged as investigation item.
  • paldocs-dev namespace: Teardown after prod verification. Low risk -- already 502.
  • No downstream consumers: paldocs is a UI service. Deployment only affects end-user access.

Decomposition Assessment

Revised assessment: The first review flagged decomposition based on 7 AC across 3 repos. The updated issue reduced to 2 repos and the work is primarily sequential kubectl operations (namespace -> secrets -> ArgoCD app -> ingress -> verify). This is a manual ops deployment, not agent-driven code changes. The 5-minute rule targets agent code passes. For human-executed ops work, these are sequential steps in a single deployment workflow -- decomposing into separate board items would create unnecessary ticket overhead.
No decomposition needed. The checklist in the issue body already provides the ordered sub-steps. This is appropriate for an ops ticket.

Recommendations

Remaining items that must be addressed before READY:
  • [BODY] Fix AC #6: Remove "db:migrate runs on pod startup via entrypoint (PR #21 wired this)". Replace with: "Entrypoint starts cleanly without attempting db:migrate (shared DB, Python-managed schema)." The bin/docker-entrypoint explicitly skips migrations -- this AC is factually wrong and would cause confusion during validation.
  • [BODY] Fix Related section: service-onboarding-sop does not exist in pal-e-docs. Either create the SOP or remove the reference to avoid dangling links.
  • [SCOPE] Create user story entry story-paldocs-infra on project-paldocs user-stories section. (Foundational work -- acceptable to defer but note should exist for traceability.)
  • [SCOPE] Create architecture note arch-ci-cd for CI/CD component. (Label exists on board item but backing note is missing.)
Minimum for READY: Fix AC #6 [BODY]. The [SCOPE] items are deferrable for infrastructure work but should be created before the ticket moves to done. The service-onboarding-sop reference [BODY] is a minor cleanup.