Upgrading

Overview

Keep your self-hosted sovseal deployment up to date with the latest features, schema optimizations, and security patches.

Upgrade Steps

Follow these steps to safely pull new images and apply migrations.

Step 1: Backup Your Data

Always run a database backup before upgrading the stack:

docker exec -t sovseal-db pg_dump -U postgres -d sovseal > backup_pre_upgrade.sql

Step 2: Pull the Latest Image

Fetch the latest containers from the repository:

docker compose pull

Step 3: Run Database Migrations

We use Alembic to manage relational schema changes in Python containers. Migrations execute automatically during image boot. If you are applying them manually, run:

docker compose run --entrypoint "alembic upgrade head" api-server

Step 4: Restart the Stack

Restart the containers to apply environmental changes:

docker compose up -d --force-recreate

Upgrading to Auth-by-Default (v1.x)

Starting with version 1.0.0, authentication is enabled by default. If you are upgrading from a pre-auth deployment, select one of the following integration paths:

Option 1: Legacy Shared Admin Key (Fastest)

Keep your current integrations working without modifying client code. Set ADMIN_API_KEY to your existing key in your .env file:

ADMIN_API_KEY="your-shared-key"

Requests carrying Authorization: Bearer <your-shared-key> will continue to be allowed.

Option 2: Per-User API Keys (Recommended)

Transition your team to granular credentials:

1. Open http://localhost:3000 to access the Dashboard setup wizard.
2. Register an admin account and issue individual API keys for developers and agents.
3. Switch client initializations to the newly generated key prefixes.

Option 3: Local Dev Override (Not for Production)

Disable authorization entirely for offline sandboxes:

AUTH_DISABLED=true

Troubleshooting Migration Failures

If you encounter database lock or migration errors during container startup:

1. Inspect Alembic logs:

   docker compose logs api-server | grep -i alembic

2. If the schema gets corrupted or unaligned, check the database status:

   docker compose exec api-server alembic current

3. To force a hard reset of database volumes (Warning: this deletes all user data and memory history):

   docker compose down -v
   make up