Upgrade Guide

This guide covers upgrading FireBackup Enterprise between versions, including breaking changes, migration steps, and rollback procedures.

Version Numbering

FireBackup follows semantic versioning (SemVer):

MAJOR.MINOR.PATCH
  │     │     └── Bug fixes, security patches
  │     └──────── New features, backward compatible
  └────────────── Breaking changes

Version Type	Impact	Example
Patch	No action needed	1.5.0 → 1.5.1
Minor	Review release notes	1.5.0 → 1.6.0
Major	Follow migration guide	1.x → 2.0.0

Before Upgrading

Pre-Upgrade Checklist

• Review release notes
• Check breaking changes for your version
• Backup database
• Backup configuration files
• Test upgrade in staging environment
• Schedule maintenance window
• Notify users if needed
• Verify rollback procedure

Backup Database

# Docker
docker exec firebackup-postgres pg_dump -U postgres firebackup > backup_$(date +%Y%m%d).sql

# Kubernetes
kubectl exec -n firebackup deployment/postgres -- \
  pg_dump -U postgres firebackup > backup_$(date +%Y%m%d).sql

Backup Configuration

# Docker Compose
cp .env .env.backup
cp docker-compose.yml docker-compose.yml.backup

# Kubernetes
kubectl get configmap -n firebackup -o yaml > configmaps_backup.yaml
kubectl get secret -n firebackup -o yaml > secrets_backup.yaml
helm get values firebackup -n firebackup > values_backup.yaml

Upgrade Procedures

Docker Compose Upgrade

Step 1: Stop Workers

docker compose stop backup-worker pitr-worker

Step 2: Pull New Images

# Update to specific version
sed -i 's/:1.5.0/:1.6.0/g' docker-compose.yml

# Or use latest (not recommended for production)
docker compose pull

Step 3: Run Database Migrations

docker compose up -d api
docker exec firebackup-api npx prisma migrate deploy

Step 4: Restart All Services

docker compose up -d

Step 5: Verify Upgrade

# Check service health
docker compose ps

# Check version
docker exec firebackup-api node -e "console.log(require('./package.json').version)"

# Check logs for errors
docker compose logs --tail=100 api

Kubernetes Upgrade

Step 1: Update Helm Values

# values.yaml
global:
  image:
    tag: "1.6.0"  # New version

Step 2: Dry Run

helm upgrade firebackup firebackup/firebackup \
  --namespace firebackup \
  --values values.yaml \
  --dry-run

Step 3: Upgrade

helm upgrade firebackup firebackup/firebackup \
  --namespace firebackup \
  --values values.yaml \
  --wait \
  --timeout 10m

Step 4: Verify

# Check rollout status
kubectl rollout status deployment/firebackup-api -n firebackup
kubectl rollout status deployment/firebackup-worker -n firebackup

# Check pods
kubectl get pods -n firebackup

# Check logs
kubectl logs -f deployment/firebackup-api -n firebackup --tail=100

Zero-Downtime Upgrade

For production environments requiring zero downtime:

# Kubernetes deployment strategy
spec:
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 0
  minReadySeconds: 30

Upgrade command:

# Set new image with controlled rollout
kubectl set image deployment/firebackup-api \
  api=firebackup/api:1.6.0 \
  -n firebackup

# Monitor rollout
kubectl rollout status deployment/firebackup-api -n firebackup

# If issues, rollback
kubectl rollout undo deployment/firebackup-api -n firebackup

Database Migrations

Automatic Migrations

Migrations run automatically on API startup:

// main.ts
await app.get(PrismaService).onModuleInit();

Manual Migrations

For controlled migration:

# Check pending migrations
npx prisma migrate status

# Apply migrations
npx prisma migrate deploy

# Generate client (if schema changed)
npx prisma generate

Migration Troubleshooting

If migration fails:

# Check migration status
npx prisma migrate status

# Reset failed migration (CAUTION: may lose data)
npx prisma migrate reset --skip-seed

# Apply specific migration
npx prisma migrate resolve --applied "20240115_add_column"

Rollback Procedures

Docker Compose Rollback

# Stop all services
docker compose down

# Restore previous version
cp docker-compose.yml.backup docker-compose.yml
cp .env.backup .env

# Restore database if needed
docker compose up -d postgres
sleep 10
docker exec -i firebackup-postgres psql -U postgres firebackup < backup_20240115.sql

# Start services
docker compose up -d

Kubernetes Rollback

# View revision history
helm history firebackup -n firebackup

# Rollback to previous revision
helm rollback firebackup -n firebackup

# Rollback to specific revision
helm rollback firebackup 5 -n firebackup

# Verify rollback
kubectl get pods -n firebackup
kubectl rollout status deployment/firebackup-api -n firebackup

Database Rollback

# Restore from backup
kubectl exec -i deployment/postgres -n firebackup -- \
  psql -U postgres firebackup < backup_20240115.sql

# Or use pg_restore for custom format
pg_restore -h localhost -U postgres -d firebackup backup.dump

Version-Specific Guides

Upgrading to v2.0.0

Major breaking changes in v2.0:

Breaking Changes

1. New authentication flow

   • OAuth tokens now use RS256
   • Requires new JWT_PRIVATE_KEY and JWT_PUBLIC_KEY

2. Database schema changes

   • backups table renamed columns
   • New audit_logs table

3. API changes

   • /api/v1/backups response format changed
   • Pagination now uses cursor-based

Migration Steps

# 1. Generate new keys
openssl genrsa -out jwt.key 4096
openssl rsa -in jwt.key -pubout -out jwt.key.pub

# 2. Add to environment
echo "JWT_PRIVATE_KEY=$(cat jwt.key | base64 -w 0)" >> .env
echo "JWT_PUBLIC_KEY=$(cat jwt.key.pub | base64 -w 0)" >> .env

# 3. Run migration script
docker exec firebackup-api node scripts/migrate-v2.js

# 4. Update API integrations
# Review API changelog for response changes

Upgrading to v1.5.0

New Features

• Point-in-Time Recovery (PITR)
• Webhook notifications
• Audit logging

Migration Steps

# 1. Add new environment variables
echo "PITR_ENABLED=true" >> .env
echo "AUDIT_LOG_RETENTION_DAYS=90" >> .env

# 2. Run migrations
docker exec firebackup-api npx prisma migrate deploy

# 3. Start PITR worker
docker compose up -d pitr-worker

Upgrading from v1.2.x to v1.3.x

Database Migration Required

-- Run manually if automatic migration fails
ALTER TABLE backups ADD COLUMN compression_ratio FLOAT;
ALTER TABLE projects ADD COLUMN pitr_enabled BOOLEAN DEFAULT false;
CREATE INDEX idx_backups_created_at ON backups(created_at);

Health Checks After Upgrade

Verify All Services

# API health
curl https://api.firebackup.io/health

# Expected response
{
  "status": "healthy",
  "version": "1.6.0",
  "checks": {
    "database": "ok",
    "redis": "ok",
    "storage": "ok"
  }
}

Verify Core Functionality

# List projects
curl -H "Authorization: Bearer $TOKEN" \
  https://api.firebackup.io/api/v1/projects

# Execute test backup
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"projectId": "proj_xxx"}' \
  https://api.firebackup.io/api/v1/backups

# Check worker status
docker exec firebackup-worker node -e "console.log('Worker healthy')"

Monitor for Issues

# Watch logs for errors
docker compose logs -f --tail=100 2>&1 | grep -i error

# Check metrics
curl http://localhost:9090/metrics | grep firebackup

# Verify scheduled jobs
docker exec firebackup-redis redis-cli LLEN bull:backups:waiting

Upgrade Best Practices

Testing

1. Staging environment first

   • Mirror production configuration
   • Run full test suite
   • Test backup/restore operations

2. Canary deployments

   # Deploy to subset first
   kubectl set image deployment/firebackup-api \
     api=firebackup/api:1.6.0 \
     -n firebackup \
     --record
   kubectl rollout pause deployment/firebackup-api -n firebackup
   # Monitor, then continue
   kubectl rollout resume deployment/firebackup-api -n firebackup

Communication

1. Internal notification

   • Notify operations team
   • Update runbooks
   • Schedule on-call coverage

2. User notification (if needed)

   • Announce maintenance window
   • Document expected downtime
   • Provide status page updates

Documentation

1. Record the upgrade

   • Date and time
   • Previous and new version
   • Any issues encountered
   • Changes made

2. Update runbooks

   • New configuration options
   • Changed procedures
   • New troubleshooting steps

Upgrade Schedule

Recommended Frequency

Version Type	Frequency	Urgency
Patch (security)	Immediate	High
Patch (bug fix)	Within 1 week	Medium
Minor	Within 1 month	Low
Major	Within 3 months	Planning required

LTS Support

Version	Release Date	End of Support
1.x LTS	2024-01-01	2026-01-01
2.x	2025-01-01	TBD

Troubleshooting

Common Issues

Migration Timeout

Error: Migration lock timeout

Solution:

# Check for blocking transactions
SELECT * FROM pg_stat_activity WHERE state = 'active';

# Kill blocking query if safe
SELECT pg_terminate_backend(pid);

# Retry migration
npx prisma migrate deploy

Container Won't Start

Error: Container unhealthy

Solution:

# Check logs
docker logs firebackup-api --tail=200

# Common fixes:
# - Verify environment variables
# - Check database connectivity
# - Ensure migrations completed

Worker Not Processing

Error: Jobs stuck in queue

Solution:

# Check worker connection
docker exec firebackup-worker redis-cli -u $REDIS_URL PING

# Clear stalled jobs
docker exec firebackup-worker node -e "
const { Queue } = require('bullmq');
const queue = new Queue('backups');
await queue.clean(0, 0, 'stalled');
"

Getting Help

If you encounter issues:

1. Check release notes
2. Search GitHub issues
3. Contact enterprise support

Related

• Docker Deployment - Docker configuration
• Kubernetes Deployment - K8s configuration
• High Availability - HA setup
• Security Hardening - Security configuration