231 lines
9.8 KiB
Markdown
231 lines
9.8 KiB
Markdown
# Platform Operations implementation tasks
|
||
|
||
- Status: Ready for stakeholder review — implementation not authorized
|
||
- Canonical plan: `tasks/plan.md`
|
||
|
||
## Task 0: Resolve implementation inputs and preserve the implementation gate
|
||
|
||
**Description:** Use the approved manual Qlockify-style specification to collect the concrete values and service contracts required for later implementation while preserving the separate explicit build-authorization gate.
|
||
|
||
**Acceptance criteria:**
|
||
- [x] Revised Platform Operations spec is explicitly approved.
|
||
- [x] ADRs 0001–0003 match the approved topology, manual release, and font decisions.
|
||
- [ ] Production connection values, protected secrets, repository URLs, service commands/routes, and responsible operators are recorded outside public Git where required.
|
||
- [ ] Stakeholder explicitly authorizes creation of deployment implementation artifacts.
|
||
|
||
**Verification:** Approved specification, clean documentation review, resolved slice inputs, and explicit build authorization.
|
||
|
||
**Dependencies:** None
|
||
|
||
**Files likely touched:** spec and ADRs only
|
||
|
||
**Estimated scope:** Small
|
||
|
||
## Task 1: Define safe configuration and release records
|
||
|
||
**Description:** Define tracked placeholders, external protected secrets, deployment locking, and non-secret active/previous release records.
|
||
|
||
**Acceptance criteria:**
|
||
- [ ] Release record contains three SHAs, local image ids, migration, backup, operator, and health evidence.
|
||
- [ ] Configuration examples contain no real or plausible secret values.
|
||
- [ ] Font provenance uses frontend commit/build only; no second asset path exists.
|
||
|
||
**Verification:** Schema/format tests, secret scan, invalid-record tests.
|
||
|
||
**Dependencies:** Task 0
|
||
|
||
**Files likely touched:** examples/schema/tests/docs, maximum 5 files
|
||
|
||
**Estimated scope:** Medium
|
||
|
||
## Task 2: Implement PostgreSQL and Redis Compose foundation
|
||
|
||
**Description:** Add pinned PostgreSQL 18 and Redis 7 Alpine, private data network, volumes, authentication, health, resources, and approved Redis AOF choice.
|
||
|
||
**Acceptance criteria:**
|
||
- [ ] Both services become healthy with explicit limits/tags.
|
||
- [ ] Neither publishes a host port.
|
||
- [ ] Redis is excluded from backup and loss does not affect PostgreSQL authority.
|
||
|
||
**Verification:** Compose validation, health, port/network, volume, Redis-loss tests.
|
||
|
||
**Dependencies:** Task 1
|
||
|
||
**Files likely touched:** Compose/config/tests, maximum 5 files
|
||
|
||
**Estimated scope:** Medium
|
||
|
||
## Task 3: Implement backend, worker, and one-off boundaries
|
||
|
||
**Description:** Wire API/worker plus separate migration/import/admin commands and graceful lifecycle.
|
||
|
||
**Acceptance criteria:**
|
||
- [ ] Migration completes before API/worker readiness.
|
||
- [ ] Normal startup never runs import/admin; import uses one exact read-only path.
|
||
- [ ] `first-start.sh` starts data services, migrates, imports and reconciles the pinned archive, then starts public services only after success.
|
||
- [ ] Worker is private/event-driven and uses pinned pre-1.0 Asynq `v0.26.0`.
|
||
|
||
**Verification:** First-start, ordinary-startup, migration/import failure, checksum/count reconciliation, idempotent no-op, and shutdown integration tests.
|
||
|
||
**Dependencies:** Task 2 and approved backend commands
|
||
|
||
**Files likely touched:** Compose/service wrappers/tests, maximum 5 files per slice
|
||
|
||
**Estimated scope:** Medium
|
||
|
||
## Task 4: Implement frontend build and font health
|
||
|
||
**Description:** Build the nested frontend checkout normally and verify static SPA/font output without deployment copies or injection.
|
||
|
||
**Acceptance criteria:**
|
||
- [ ] Build uses recorded frontend commit at/after `64f5ac2`.
|
||
- [ ] Expected font resource returns 200 with correct content type.
|
||
- [ ] Deployment repository contains no font binary, `FontLicense.txt`, fetch, credential, or alternate path.
|
||
|
||
**Verification:** Build/static health plus repository-policy scan.
|
||
|
||
**Dependencies:** Task 1 and approved frontend build contract
|
||
|
||
**Files likely touched:** frontend deployment wrapper/service/tests, maximum 5 files
|
||
|
||
**Estimated scope:** Medium
|
||
|
||
## Task 5: Implement Nginx and automatic TLS
|
||
|
||
**Description:** Adapt Qlockify's Nginx/Certbot pattern for canonical routing, Let's Encrypt, API/frontend separation, exact SSE behavior, security headers, and health.
|
||
|
||
**Acceptance criteria:**
|
||
- [ ] Only 80/443 are public; unknown hosts reject and canonical redirect is exact.
|
||
- [ ] Staging/production issuance and renewal/reload pass.
|
||
- [ ] SSE heartbeat/reconnect streams without buffering/cache/compression.
|
||
|
||
**Verification:** `nginx -t`, external TLS/header/routing checks, streamed SSE test.
|
||
|
||
**Dependencies:** Tasks 3–4 and approved routes/CSP
|
||
|
||
**Files likely touched:** Nginx/Certbot assets/tests, maximum 5 files per slice
|
||
|
||
**Estimated scope:** Medium
|
||
|
||
## Checkpoint A: Runtime MVP foundation
|
||
|
||
- [ ] Tasks 1–5 pass from clean nested checkouts.
|
||
- [ ] Only Nginx is public; migration/import/admin/font/SSE boundaries behave correctly.
|
||
- [ ] No secret/raw data/runtime/font duplication enters deployment Git.
|
||
|
||
## Task 6: Adapt Qlockify manual deploy and rollback
|
||
|
||
**Description:** Modify Qlockify's deploy flow for ZarinPal paths/services and three-hash release records while keeping interactive Git pulls as a separate operator prerequisite and removing unconditional destructive Git synchronization.
|
||
|
||
**Acceptance criteria:**
|
||
- [ ] Operator manually fast-forwards all three repositories to latest `origin/main`; the deployment command performs no pull and records all three hashes before build.
|
||
- [ ] Dirty/diverged checkout, build, migration, or health failure preserves the active release; a manual pull failure prevents deployment from starting.
|
||
- [ ] Previous hashes rebuild/restore within 15 minutes without automatic down migration.
|
||
|
||
**Verification:** Script tests plus induced staging failures and timed rollback drill.
|
||
|
||
**Dependencies:** Checkpoint A
|
||
|
||
**Files likely touched:** deploy script/release helper/tests/docs, maximum 5 files per slice
|
||
|
||
**Estimated scope:** Medium
|
||
|
||
## Task 7: Adapt Qlockify encrypted backup/upload
|
||
|
||
**Description:** Reuse Qlockify's PostgreSQL dump, OpenSSL, rclone upload, and retention flow with ZarinPal paths/services/credentials and a non-secret manifest.
|
||
|
||
**Acceptance criteria:**
|
||
- [ ] Package contents, plain-SQL header/checksums, encryption, and remote verification gate success.
|
||
- [ ] Exactly three verified encrypted local and seven remote backups are retained.
|
||
- [ ] `.env`, secrets, Redis, TLS, CSV, credentials, logs, monitoring, font, and license are excluded.
|
||
|
||
**Verification:** Fixture database/object-store tests, exclusion inspection, failed-upload/cleanup tests.
|
||
|
||
**Dependencies:** Tasks 1–3 and approved backup inputs
|
||
|
||
**Files likely touched:** adapted backup/upload scripts/tests/docs, maximum 5 files per slice
|
||
|
||
**Estimated scope:** Medium
|
||
|
||
## Task 8: Adapt Qlockify guarded restore
|
||
|
||
**Description:** Reuse Qlockify download/decrypt/restore flow while requiring explicit backup id, exact destination, empty target, and all production guards.
|
||
|
||
**Acceptance criteria:**
|
||
- [ ] Every absent/mismatched production factor aborts before mutation.
|
||
- [ ] No environment/secret/Redis restoration occurs.
|
||
- [ ] Clean restore passes schema/count/tenant/login/cold-cache/worker/SSE checks within two hours.
|
||
|
||
**Verification:** Disposable-database tests, guard negative matrix, timed rehearsal.
|
||
|
||
**Dependencies:** Task 7
|
||
|
||
**Files likely touched:** adapted restore scripts/tests/docs, maximum 5 files per slice
|
||
|
||
**Estimated scope:** Medium
|
||
|
||
## Task 9: Bootstrap and accept MVP server
|
||
|
||
**Description:** Follow the reviewed bootstrap runbook, run the guarded first-start migration/import/application sequence, perform separate demo setup, and capture MVP evidence.
|
||
|
||
**Acceptance criteria:**
|
||
- [ ] Access/firewall/Docker/DNS/TLS/deployment boundaries pass.
|
||
- [ ] Three-hash release, migration, import, accounts, tenant isolation, worker/SSE, and font pass.
|
||
- [ ] MVP manual health/log/disk/certificate/queue checks and encrypted backup/restore pass.
|
||
|
||
**Verification:** Completed bootstrap/acceptance record.
|
||
|
||
**Dependencies:** Tasks 6–8 and approved server/window
|
||
|
||
**Files likely touched:** non-sensitive release/evidence records only
|
||
|
||
**Estimated scope:** Operational session
|
||
|
||
## Checkpoint B: MVP ready
|
||
|
||
- [ ] Every MVP acceptance criterion passes.
|
||
- [ ] Active/previous three-hash releases and rollback are ready.
|
||
- [ ] Clean restore meets RPO/RTO.
|
||
- [ ] Stakeholder explicitly confirms the core project is ready, opening the observability phase.
|
||
|
||
## Task 10: Add Prometheus and private exporters
|
||
|
||
**Description:** Add post-MVP collection for application, worker/SSE, PostgreSQL/Redis, host/container, backup/restore, and TLS signals.
|
||
|
||
**Acceptance criteria:**
|
||
- [ ] Required signals appear with bounded labels and retention.
|
||
- [ ] Prometheus/exporters are private and resource-limited.
|
||
- [ ] Merchant/user/request/card identifiers are absent from metric labels.
|
||
|
||
**Verification:** Target health, signal/cardinality/resource tests.
|
||
|
||
**Dependencies:** Checkpoint B
|
||
|
||
**Files likely touched:** split into <=5-file monitoring slices
|
||
|
||
**Estimated scope:** Multiple Medium slices
|
||
|
||
## Task 11: Add Grafana dashboards and alerts
|
||
|
||
**Description:** Add private dashboards, release correlation, actionable symptom alerts, runbook links, and delivery testing.
|
||
|
||
**Acceptance criteria:**
|
||
- [ ] Service, worker/SSE, data, host, backup, and TLS dashboards answer the spec's operator questions.
|
||
- [ ] Only page/ticket alerts exist and each is actionable.
|
||
- [ ] Induced failures alert and can be diagnosed without source archaeology.
|
||
|
||
**Verification:** Dashboard review, induced failure, alert test-fire, redaction check.
|
||
|
||
**Dependencies:** Task 10
|
||
|
||
**Files likely touched:** split into <=5-file dashboard/alert slices
|
||
|
||
**Estimated scope:** Multiple Medium slices
|
||
|
||
## Final observability checkpoint before AI
|
||
|
||
- [ ] Prometheus/Grafana phase meets its acceptance criteria.
|
||
- [ ] Alert delivery and runbook ownership are proven.
|
||
- [ ] Stakeholder explicitly approves beginning AI implementation.
|
||
- [ ] No CI/CD pipeline or automated deployment system was introduced.
|