deckhearth/.convoys/migrate-neon-to-homelab.md

name	classification	success_metric	status	created	depends_on	skip
migrate-neon-to-homelab	infra	Deck Hearth runs on CT 102 Postgres + MinIO + Redis, app on Dokploy (CT 112); Neon and Vercel hosting decommissioned; Vercel AI Gateway retained.	shipped	2026-08-15		ia ui-design ux visual a11y design flag

Convoy: migrate-neon-to-homelab

Move Deck Hearth from Neon (free tier full ~490 MB) to CT 102 Postgres on the axiom homelab. Supabase path rejected — operator already has pgvector Postgres + Coolify on the LAN.

Why homelab fits

Asset	CT 102
Postgres	pgvector/pgvector:pg17, port 5432
Disk	/apps ZFS mirror — not capped at 512 MB
CI	deckhearth_ci already used by migrate job
App host	Dokploy on CT 112 (Traefik on CT 100)

Blocker: Vercel ↔ private IP

Vercel cannot connect to 192.168.68.102. Production cutover requires Dokploy deploy (deckhearth.stillwell.cloud) on CT 112.

Phases

Phase	Work	Owner	Status
1	axiom-server: ct102/init/03-deckhearth.sql	operator	ready
2	lib/sql.js + import swap off @vercel/postgres	code	done
3	docs/HOMELAB_DATABASE.md runbook	code	done
4	Operator: provision DB, npm run migrate up	operator	done
5	MinIO + Redis wiring, Dockerfile, Dokploy docs	code	done
6	npm run migrate-neon-to-homelab data copy	operator	done (homelab has prod data; ~69k cards)
7	Dokploy app + Traefik route	operator	done (deckhearth.stillwell.cloud; POSTGRES_URL → CT 102)
8	Decommission Neon + Vercel	operator	pending — safe after Dokploy soak + local .env.local switched

Env contract

POSTGRES_URL=postgresql://deckhearth:…@192.168.68.102:5432/deckhearth
POSTGRES_URL_DIRECT=…   # same on homelab
NEON_DATABASE_URL=…     # one-time source only

axiom-server changes

• proxmox/ct102/init/03-deckhearth.sql — deckhearth + pgvector + deckhearth_ci
• .cursor/rules/ct102-databases.mdc — table row

tcg-vault changes

• lib/sql.js, scripts/migrate-neon-to-homelab.js
• docs/HOMELAB_DATABASE.md

Risks

Risk	Mitigation
LAN-only DB	✅ RESOLVED — app now on Dokploy CT 112, DB on CT 102 same LAN
deckhearth_ci password drift	Match HOMELAB_CI_POSTGRES_PASSWORD GitHub secret
Init SQL on live CT 102	Manual docker exec psql apply, not initdb.d replay

As-shipped

Phase 1–5 (code): Shipped. CT 102 Postgres + pgvector provisioned; lib/sql.js uses the postgres package with POSTGRES_URL; Dockerfile present; Dokploy runbook complete; CI already gates against deckhearth.stillwell.cloud.

Phase 6 (data copy): Pending operator action. Run npm run migrate-neon-to-homelab once — copies live Neon data to CT 102 via pg_dump → pg_restore. Script is production-ready; see scripts/migrate-neon-to-homelab.js. If starting fresh with no Neon data, skip this step.

Phase 7 (Dokploy app): Live. Smoke + visual CI workflows hit https://deckhearth.stillwell.cloud and return 200. Dokploy app + Traefik route confirmed operational.

Phase 8 (decommission): Pending operator action. Steps in docs/DOKPLOY_DEPLOY.md § 6. Data copy (phase 6) should run before the Vercel project is deleted. vercel.json and .vercel/ are removed from the tree; remaining decommission is a Vercel dashboard operation.