2984185e6b
Document homelab Neon teardown steps, add fix-pricing-pgmigration-order script, and refresh migrate-neon convoy status for Dokploy. Co-authored-by: Cursor <cursoragent@cursor.com>
97 lines
3.4 KiB
Markdown
97 lines
3.4 KiB
Markdown
---
|
||
name: migrate-neon-to-homelab
|
||
classification: infra
|
||
success_metric: |
|
||
Deck Hearth runs on CT 102 Postgres + MinIO + Redis, app on Dokploy (CT 112);
|
||
Neon and Vercel hosting decommissioned; Vercel AI Gateway retained.
|
||
status: shipped
|
||
created: 2026-08-15
|
||
depends_on: []
|
||
skip:
|
||
- 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
|
||
|
||
```bash
|
||
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.
|