self-hosting
Upgrading

Upgrading

How to upgrade your self-hosted Orsa instance, apply database migrations, and handle breaking changes.

Upgrade Process

1. Pull the Latest Release

cd orsa
 
# Fetch latest changes
git fetch origin
 
# Check the changelog
git log --oneline origin/main..HEAD
 
# Pull
git pull origin main

Or if you're tracking a specific release:

git fetch --tags
git checkout v1.2.0

2. Install Updated Dependencies

pnpm install

3. Run Database Migrations

# Check for new migrations
ls supabase/migrations/
 
# Apply migrations
supabase db push

For Supabase Cloud:

supabase link --project-ref your-project-ref
supabase db push

4. Regenerate Types

pnpm generate:types

5. Rebuild and Deploy

Docker Compose:

docker compose build
docker compose up -d

Kubernetes:

helm upgrade orsa ./infrastructure/k8s/orsa \
  --namespace orsa \
  --values values.yaml

Vercel:

# API, Web, and Docs auto-deploy on git push if connected to Vercel
git push origin main

Browser Worker (Fly.io):

cd infrastructure/fly
./deploy.sh production

6. Verify

# Health check
curl https://api.yourdomain.com/api/v1/health
 
# Check version (if exposed)
curl https://api.yourdomain.com/api/v1/version

Migration Strategy

Automatic Migrations

All schema changes live in supabase/migrations/ as numbered SQL files. Supabase applies them in order and tracks which have been run.

supabase/migrations/
├── 00001_initial_schema.sql
├── 00002_rls_policies.sql
├── 00003_seed_data.sql
├── 00004_merchant_descriptors_expansion.sql
├── 00005_webhooks.sql
└── 00006_new_feature.sql   ← new migration in update

Manual Migration Steps

Some upgrades may require manual steps (documented in the release notes). Common scenarios:

  • New required environment variable — Add to your .env.local or secrets
  • New external dependency — Configure a new provider (e.g., a new storage backend)
  • Data backfill — Run a one-time script to populate new columns

Rolling Back

If an upgrade causes issues:

# Revert to previous version
git checkout v1.1.0
pnpm install
pnpm build
 
# Database rollback (if migration was destructive)
# Check the migration file for a rollback section, or write a reverse migration

Important: Database migrations are generally forward-only. Always back up your database before upgrading:

# Supabase Cloud
supabase db dump -f backup_$(date +%Y%m%d).sql
 
# Self-hosted Postgres
pg_dump -U postgres -d orsa > backup_$(date +%Y%m%d).sql

Breaking Changes Policy

Versioning

Orsa follows Semantic Versioning (opens in a new tab):

  • Patch (0.1.x) — Bug fixes, no breaking changes, no migration needed
  • Minor (0.x.0) — New features, possible new migrations, backward-compatible
  • Major (x.0.0) — Breaking changes, required migrations, possible data format changes

What Counts as Breaking

  • Removing or renaming an API endpoint
  • Changing the response shape of an existing endpoint
  • Removing a database column or table
  • Changing environment variable names
  • Dropping support for a dependency version

What's Not Breaking

  • Adding new API endpoints
  • Adding optional fields to existing responses
  • Adding new database tables or columns
  • Adding new environment variables with defaults
  • New migrations that only add (not modify/remove)

Release Notes

Every release includes:

  1. What changed — New features, improvements, fixes
  2. Migration steps — Required database migrations
  3. Breaking changes — Explicitly called out with upgrade instructions
  4. New environment variables — Listed with descriptions and defaults

Check GitHub Releases (opens in a new tab) for the full changelog.

Recommended Upgrade Workflow

# 1. Backup database
supabase db dump -f backup_$(date +%Y%m%d).sql
 
# 2. Read release notes
open https://github.com/paragonhq/orsa/releases
 
# 3. Pull update
git pull origin main
 
# 4. Install dependencies
pnpm install
 
# 5. Apply migrations
supabase db push
 
# 6. Regenerate types
pnpm generate:types
 
# 7. Build
pnpm build
 
# 8. Deploy (method depends on your setup)
docker compose up -d --build
# or: helm upgrade orsa ...
# or: git push (Vercel auto-deploy)
 
# 9. Verify
curl https://api.yourdomain.com/api/v1/health
 
# 10. Monitor logs for 15 minutes
docker compose logs -f --tail=50
# or: kubectl logs -n orsa -l app=orsa-api --tail=50 -f
ConfigurationTroubleshooting