transcription/docs/v6_0_hosting_migration_plan.md

V6.0 Hosting Migration Formal Plan

This plan formalizes the V6.0 roadmap objective: move from local-only operation to secure, stable remote hosting.

1. Confirmed Infrastructure Decisions

• Runtime host: dedicated Debian/Ubuntu VM on Proxmox 8.4.x.
• Remote ingress: Cloudflare Tunnel + Cloudflare Access with public hostnames per internal service.
• Backup target: Synology DS420j for PostgreSQL dumps and restore points.
• Out of scope for V6.0: Synology as primary live upload/image storage.

2. Target Runtime Topology

The production stack is deployed with Docker Compose on the Proxmox VM:

1. app service (FastAPI + NiceGUI runtime)
2. worker service (async transcription worker)
3. postgres service (primary datastore)
4. cloudflared service (tunnel ingress to app endpoints)

Persistence:

• PostgreSQL data: durable local volume on Proxmox VM.
• App data/log paths: durable local volume(s) on Proxmox VM.
• Backups: scheduled PostgreSQL dump artifacts replicated to Synology DS420j.

3. V6.0 Workstreams

3.1 Deployment and configuration

1. Produce production-ready Docker/Compose definitions for app, worker, postgres, and cloudflared.
2. Move runtime settings to environment-based configuration (DB, uploads, prompts, logging, secrets).
3. Add operational defaults (health checks, restart policies, predictable service dependencies).

3.2 Database migration (SQLite -> PostgreSQL)

1. Define a deterministic migration method from SQLite to PostgreSQL.
2. Run migration in staging-like environment and validate entity counts and key relationships.
3. Execute cutover with rollback guardrails and preserved evidence/provenance history.

Implemented workflow references:

• tools/export_import_migration.py (export, import, migrate, verify)
• docs/data_migration.md for cutover and rollback procedure

3.3 Cloudflare remote access

1. Configure tunnel routing for service hostnames.
2. Apply Cloudflare Access policies for identity-gated remote access.
3. Keep non-required administrative/internal surfaces LAN-only unless explicitly approved.

3.4 Backup, restore, rollback

1. Define backup schedule, retention, and artifact naming/versioning.
2. Validate restore drill from Synology-hosted dump artifacts.
3. Document rollback procedure for deployment failure and migration failure scenarios.

3.5 Validation and release gate

1. /healthz confirms app and worker healthy in deployed environment.
2. One end-to-end document -> source -> job workflow succeeds through remote access.
3. Backup/restore drill completes and data integrity checks pass.

4. Deliverables

• Production-ready docker-compose deployment for app + worker + PostgreSQL + cloudflared.
• Environment configuration model suitable for production secrets and runtime overrides.
• Repeatable SQLite-to-PostgreSQL migration procedure with cutover checklist.
• Updated runbook content for deploy, rollback, backup, and restore.

5. Exit Criteria (V6.0 Complete)

• Health and worker liveness are green in deployed runtime.
• Remote transcription workflow is successful and stable.
• Backup and restore are tested and documented.
• Evidence/provenance guarantees remain intact (append-only attempt history and traceability preserved).

6. Open Decisions to Finalize During Implementation

• Hostname inventory and naming convention for each remotely exposed internal service.
• Cloudflare Access policy granularity (per-service policy shape and identity groups).
• Backup retention windows and RPO/RTO targets aligned with available Synology capacity.