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.

Implemented workflow references:

- `deploy/cloudflared/config.yml.example`
- `docs/cloudflare_tunnel_access.md`

## 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.

Implemented workflow references:

- `deploy/backup/create_postgres_backup.sh`
- `deploy/backup/restore_postgres_backup.sh`
- `docs/backup_restore.md`

## 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.