Repository Impact: Switch to Local Postgres

Summary

The implementation is owned entirely by anuvax-cms. Product Main owns the approved outcome, repository-scoped handoffs, progress, and completion review. The Python and Unity runtime contracts do not change because the CMS remains reachable through its existing host port and worker-facing HTTP API.

Ownership matrix

Repository	Owned scope	Explicit non-goals	Inputs/dependencies	Outputs/contracts	Verification
anuvax-cms	Dockerfile/Compose stack; local configuration; pgvector/Postgres/pgAdmin lifecycle; export/restore tooling; data cutover; repository docs and evidence	Production deployment; full Supabase stack; Python or Unity changes	Approved Product Main plan; Docker Desktop; Supabase CLI access; source database credentials; external service configuration	Stable Compose service/port contract; guarded migration procedure; local runtime and parity evidence	Compose validation and health; database/version/extension checks; lint, typecheck, tests, application and migration parity
anuva-python-server	No implementation change	Containerizing Python or changing worker protocol	Existing CMS worker API remains reachable on port 3000	No changed contract	Confirm no repository issue required; CMS worker-API smoke evidence covers compatibility
anuva-unity-video-creator	No implementation change	Containerizing Unity or changing render contracts	No dependency	No changed contract	Confirm no repository issue required
anuva-main-video-creator	Change brief, impact analysis, Linear handoffs, progress, completion review	CMS implementation or direct data migration	Linear ANU-5; CMS completion reports and PRs	Approved contracts and final product acceptance decision	MkDocs/index validation; planning and completion PR checks; child/PR/report verification

Contract changes

Development runtime contract

anuvax-cms changes from a host-run web process using hosted Postgres to a Compose-managed web process using the internal postgres service. The host-facing ports remain compatible with the Anuva machine configuration:

• Web: 127.0.0.1:3000
• PostgreSQL: 127.0.0.1:5432
• pgAdmin: 127.0.0.1:5050

The Python server continues to call the CMS worker API through its configured public or host URL. No request, response, authentication, or render contract is changed.

Database contract

• PostgreSQL major version remains 17.
• Payload, Mastra, and RAG continue sharing one DATABASE_URI database.
• pgvector remains required and must report version 0.8.2 for this baseline.
• Existing schemas, migration records, constraints, relationships, sequences, workspace boundaries, and vector dimensions remain semantically unchanged.
• Supabase-managed schemas and roles are not application dependencies and are not imported unless source inventory contradicts that assumption and the plan is revised before restore.

Operational contract

• docker compose up --build is the documented local start boundary.
• Health checks gate web startup on Postgres readiness.
• Named volumes persist database and pgAdmin state.
• Tracked files contain examples only; secrets and database exports remain local.
• Destructive reset commands are documented separately and never run implicitly.

Sequencing and blockers

flowchart LR
    Plan["Approved Product Main plan"] --> Stack["CMS local container stack"]
    Stack --> Migration["Supabase export, restore, and cutover"]
    Migration --> Review["Product Main completion review"]

The container stack must be merged and verified before the real data migration starts. This separates repeatable infrastructure work from the stateful operation that handles sensitive data and may require controlled retries.

Repository Linear issue drafts

Issue 1: Add the containerized local CMS development stack

• Repository: anuvax-cms
• Priority: High
• Dependencies: None

Scope

Add a development-focused Dockerfile and Docker Compose definition for the CMS web application, PostgreSQL 17 with pgvector, and pgAdmin. Add health checks, loopback host bindings, named volumes, ignored local configuration, safe example files, deterministic image version/digest evidence, and developer lifecycle commands. Update CMS configuration only where required to remove Supabase-only assumptions and support container networking. Add guarded export/restore and parity-check tooling without running the real migration in this issue.

Acceptance

• Compose configuration validates without embedded secrets.
• web, postgres, and pgadmin start through one documented command and are reachable at the approved ports.
• PostgreSQL reports the selected 17.x maintenance version; pgvector reports 0.8.2; pgAdmin reports 9.16; resolved image digests are recorded.
• Restart preserves named-volume state and routine stop commands do not delete it.
• Payload, Mastra initialization, RAG vector operations, and the worker API smoke path work from the containerized web service against local Postgres.
• Export/restore tooling uses explicit source and target inputs, writes only to ignored local paths, and refuses destructive ambiguity.

Docs

Create the issue change folder and ImplementationPlan, ImplementationLog, and CompletionReport. Update CMS system architecture, environment/services, scripts and commands, testing guidance, .env examples, and bootstrap instructions. Return exact CMS preview URLs after every logical documentation update.

Verification

Run docker compose config, clean-build/start and health checks, database version and extension queries, persistence/restart checks, pnpm lint, pnpm typecheck, pnpm test:int, relevant Playwright smoke coverage, strict MkDocs build, and index validation. The completion report must map each acceptance check to exact redacted evidence and include rollback/recovery guidance plus Product Main sync.

Issue 2: Migrate Supabase Postgres data and verify local cutover

• Repository: anuvax-cms
• Priority: High
• Dependencies: Issue 1

Scope

Inventory the source database, create checksummed schema and data exports with the Supabase CLI, restore them into the verified local pgvector/Postgres stack, resolve only application-required ownership/extension differences, switch the local CMS configuration, and capture redacted parity and application evidence. Keep the Supabase source unchanged and retain a tested rollback path.

Acceptance

• Source inventory identifies PostgreSQL/extensions, application schemas, required roles, tables, constraints, sequences, Payload migration state, and vector index state without recording secrets or row contents.
• Schema and data dumps are generated with the Supabase CLI, stored in ignored local paths, checksummed, and verified as absent from Git.
• Restore completes into the local target with no unreviewed Supabase-managed schemas or blanket privilege weakening.
• Automated and targeted parity checks cover table counts, representative key records, constraints, sequences, migrations, workspace boundaries, Mastra tables, RAG chunks, and vector-query behavior.
• The containerized CMS, workers, Payload admin/login, primary application flows, and selected end-to-end tests pass against local Postgres.
• Restart persistence passes; rollback to the untouched Supabase URI is documented and demonstrated without deleting the accepted local volume.

Docs

Maintain the issue ImplementationPlan, ImplementationLog, and CompletionReport; update the CMS environment/service and migration/runbook documentation with redacted commands, failure handling, rollback, and version evidence. Do not place dump contents, credentials, or personal data in Markdown, Linear, or the PR.

Verification

Run Supabase CLI dump dry runs and exports, checksum validation, controlled restore and SQL parity scripts, Payload migration-status checks, database/extension queries, pnpm lint, pnpm typecheck, pnpm test:int, relevant Playwright projects, container restart/persistence tests, strict MkDocs build, and index validation. The completion report must identify skipped checks, limitations, recovery state, and the exact evidence needed for Product Main completion.

Cross-repository integration verification

• Confirm the Python worker can still reach the unchanged CMS worker API through the published port after the web application moves into Docker.
• Confirm no Python or Unity protocol/config changes are required.
• Confirm Product Main anuva doctor sees PostgreSQL on 127.0.0.1:5432 and the CMS health endpoint on its configured URL once the stack is running.
• Treat any discovered cross-repository contract change as a planning revision; do not expand a CMS child silently.

Product Main sync and completion

Each CMS completion report must link its Linear issue, implementation plan/log, PR, exact verification results, documentation previews, limitations, and recovery state. Product Main will update Progress.md, create CompletionReview.md, verify both child issues and their merged PRs, execute the end-to-end acceptance checks, and only then request approval to mark ANU-5 Done.