sojorn/sojorn_docs/legacy/BACKEND_MIGRATION_RUNBOOK.md

Sojorn Migration Runbook: Supabase to Golang VPS

This document outlines the step-by-step process for cutover from Supabase to the self-hosted Golang engine.

Phase 1: Infrastructure Setup

1. Provision VPS: Ubuntu 22.04 LTS recommended (2 vCPU, 4GB RAM minimum).
2. Install Dependencies:

   sudo apt update && sudo apt install -y postgresql postgis nginx certbot python3-certbot-nginx
   

3. Configure Database:
   • Create sojorn database.
   • Enable extensions: uuid-ossp, pg_trgm, postgis.

Phase 2: Data Migration

1. Export from Supabase:
   • Use pg_dump to export schema and data from your Supabase project.
   • Alternatively, use the Supabase CSV export for specific tables if the schema changes significantly.
2. Import to VPS:

   psql -h localhost -U youruser -d sojorn -f supabase_dump.sql
   

3. Run Go Migrations:
   • The Go backend uses golang-migrate. Ensure the version table is synced if you are not starting from scratch.

   make migrate-up
   

Phase 3: Deployment

1. Clone & Build:

   git clone <your-repo> /opt/sojorn
   cd /opt/sojorn/go-backend
   go build -o bin/api ./cmd/api/main.go
   

2. Configure Nginx:
   • Set up reverse proxy to port 8080.
   • Configure SSL with Certbot.
3. Start Systemd Service:

   sudo ./scripts/deploy.sh
   

Phase 4: Cutover (Zero Downtime Strategy)

1. Parallel Run: Keep both Supabase and Go VPS running.
2. DNS Update: Point your API subdomain (e.g., api.sojorn.net) to the new VPS IP.
3. TTL Check: Ensure DNS TTL is low (e.g., 300s) before starting.
4. Monitor: Watch logs for 4xx/5xx errors.

   journalctl -u sojorn-api -f
   

Phase 5: Decommission Supabase

1. Once traffic has fully shifted and no errors are reported, you can disable Supabase Edge Functions.
2. Keep the Supabase project active for a week as a backup database if needed.

Rollback Plan

1. If critical issues occur on the VPS, point the DNS back to the Supabase Edge Functions URL.
2. Restore any data written to the VPS back to Supabase if necessary (Dual-write during transition is recommended if possible).