Upgrades

Upgrading your self-hosted Ballast deployment.

This guide covers upgrading self-hosted Ballast deployments.

Before Upgrading

Check Release Notes

Review the release notes for your target version:

  • Breaking changes
  • Required migrations
  • New environment variables

Backup Data

Before any upgrade:

# PostgreSQL backup
pg_dump -U ballast ballast > backup_$(date +%Y%m%d).sql

# Qdrant backup (if persistent)
# Qdrant data is stored in the mounted volume

Check Compatibility

Verify external service compatibility:

Ballast VersionPostgreSQLQdrantTemporal
1.x15-161.7+1.24+

Docker Compose Upgrade

1. Pull New Images

docker compose pull

2. Stop Services

docker compose down

3. Run Migrations

If there are database migrations:

docker compose run --rm ballast migrate up

4. Start Services

docker compose up -d

5. Verify

curl http://localhost:8080/api/v1/health

Kubernetes Upgrade

Using Helm

# Update repo
helm repo update

# Check available versions
helm search repo ballast --versions

# Upgrade
helm upgrade ballast ballast/ballast --version X.Y.Z

Rolling Updates

The default Helm configuration uses rolling updates:

  • New pods start before old ones terminate
  • Zero-downtime upgrades
  • Automatic rollback on failure

Database Migrations

Ballast manages database migrations automatically on startup. For manual control:

# Check migration status
ballast migrate status

# Apply pending migrations
ballast migrate up

# Rollback last migration (use with caution)
ballast migrate down

Rollback

Docker Compose

# Stop current version
docker compose down

# Edit compose.yaml to use previous version
# Or pull specific tag
docker pull ballast/ballast:previous-version

# Start
docker compose up -d

Kubernetes

# Rollback to previous release
helm rollback ballast

# Or to specific revision
helm rollback ballast 3

Version Compatibility

API Compatibility

API endpoints maintain backward compatibility within major versions. Breaking changes only occur in major releases.

Data Compatibility

  • Upgrades are always supported
  • Downgrades may require data migration
  • Check release notes for specific guidance

Best Practices

Test upgrades first

  • Use staging environment
  • Verify functionality before production

Schedule maintenance windows

  • Communicate with users
  • Allow time for rollback if needed

Keep backups

  • Database backup before upgrade
  • Retain for at least one version cycle

Monitor after upgrade

  • Watch logs for errors
  • Verify sync operations
  • Check search functionality