Upgrading

This guide covers how to safely upgrade OpenTranscribe between versions, including pre-upgrade preparation, the upgrade process, and rollback procedures.

Pre-Upgrade Checklist

Before upgrading, complete these steps:

Back up the database -- this is non-negotiable
```
./opentr.sh backup
```

Note your current version

cat VERSION
# or check the UI footer / API response
curl -s http://localhost:5174/api/health | python3 -m json.tool

Read the changelog for the target version at CHANGELOG.md
Check for breaking changes -- major version bumps or migration notes
Test in staging first if you have a staging environment

danger

Always back up your database before upgrading. Database migrations run automatically on startup and cannot be undone without a backup.

Standard Upgrade Process

Using opentr.sh (Recommended)

# Pull latest images and restart
./opentr.sh update

This command pulls the latest Docker images from Docker Hub and recreates all containers. Database migrations run automatically when the backend starts.

Manual Upgrade

# Pull new images
docker compose pull

# Restart services with new images
docker compose up -d --force-recreate

Upgrading to a Specific Version

To pin to a specific release instead of latest:

# Pull specific version tags
docker pull davidamacey/opentranscribe-frontend:v0.3.0
docker pull davidamacey/opentranscribe-backend:v0.3.0

# Update image tags in docker-compose.prod.yml or .env, then restart
docker compose up -d --force-recreate

Database Migrations

How Migrations Work

OpenTranscribe uses Alembic for database schema migrations. On every backend startup, the system automatically:

Detects the current database schema version
Stamps untracked databases with the appropriate version
Runs any pending migrations to bring the database up to date

You do not need to run migrations manually -- they execute automatically.

Current Migration Chain

The migration chain progresses through these versions:

Migration	Description
`v010`	Baseline schema
`v020`	System settings
`v030`	LDAP authentication
`v031`	Keycloak and PKI auth
`v040`	FedRAMP compliance fields
`v050`	Search settings
`v060`	Transcript overlap
`v070-v073`	PKI security, segment constraints, status enum
`v080`	Auth configuration
`v090-v091`	Error categories, speaker suggestion source
`v100-v120`	Query performance indexes
`v130-v140`	Processing model tracking, word timestamps
`v150-v170`	File retention, local fallback, Keycloak refresh tokens
`v180-v190`	Speaker attributes, collection default prompts
`v200-v211`	Schema reconciliation, groups and sharing
`v220-v270`	Speaker clusters, auto labeling, quality metrics, ASR providers, avatars
`v280-v320`	Upload sessions, gender fields, speaker constraints, cluster names
`v330`	Shared configs and prompts
`v340`	User media sources
`v350`	Diarization disabled flag
`v351`	AI summary settings
`v352`	Requested Whisper model per-transcription
`v353`	Segment unique index fix
`v355`	Independent diarization provider settings

What to Do if Migrations Fail

If a migration fails on startup:

Check the backend logs for the specific error:

docker compose logs backend | grep -i "alembic\|migration\|error"

Restore your backup if the migration left the database in a broken state:
```
./opentr.sh restore backups/opentranscribe_backup_YYYYMMDD_HHMMSS.sql
```
Report the issue -- migration failures are bugs. File an issue with the error output.

note

All OpenTranscribe migrations use idempotent SQL (IF NOT EXISTS, DO $$ ... END $$ blocks), which means they are safe to re-run. If a migration partially completed, restarting the backend will attempt to finish it.

Rolling Back

Reverting to a Previous Version

If an upgrade causes issues, you can roll back:

# 1. Stop all services
docker compose down

# 2. Restore the database backup you made before upgrading
docker compose up -d postgres
# Wait for postgres to be ready
until docker compose exec postgres pg_isready -U postgres; do sleep 2; done
docker compose exec -T postgres psql -U postgres opentranscribe < backups/opentranscribe_backup_YYYYMMDD_HHMMSS.sql

# 3. Pull the previous version images
docker pull davidamacey/opentranscribe-frontend:vPREVIOUS
docker pull davidamacey/opentranscribe-backend:vPREVIOUS

# 4. Tag them as latest (so compose uses them)
docker tag davidamacey/opentranscribe-frontend:vPREVIOUS davidamacey/opentranscribe-frontend:latest
docker tag davidamacey/opentranscribe-backend:vPREVIOUS davidamacey/opentranscribe-backend:latest

# 5. Start all services
docker compose up -d

warning

You must restore the database backup when rolling back. Newer migrations may have altered the schema in ways incompatible with older code.

Major Version Upgrades

Major version upgrades (e.g., 0.x to 1.x) may include breaking changes that require extra steps.

Embedding Migration (v3 to v4)

When upgrading across the speaker embedding architecture change:

speakers_v3 uses 512-dimensional pyannote embeddings
speakers_v4 uses 256-dimensional WeSpeaker embeddings
The speakers alias automatically points to the active index

The migration runs through the Admin UI:

Navigate to Admin Settings > Speaker Embeddings
Start the embedding migration -- this re-extracts embeddings for all speakers
Monitor progress in the migration panel
Once complete, the alias swaps atomically to the new index

tip

Embedding migration can take significant time depending on the number of speakers and media files. Plan accordingly and run during a maintenance window.

Other Major Upgrade Considerations

OpenSearch version changes: May require reindexing all data
Model format changes: New AI models download automatically on first use
Authentication changes: Review auth settings after upgrading, especially for LDAP/Keycloak configurations
Configuration changes: Compare your .env with .env.example to identify new required variables

Verifying the Upgrade

After upgrading, verify everything is working:

1. Check Service Health

# All containers should be running and healthy
./opentr.sh status

# Or check directly
docker compose ps

2. Check Backend Logs

# Look for successful startup and migration messages
docker compose logs backend --tail=50

# Verify no migration errors
docker compose logs backend | grep -i "error\|failed\|exception" | head -20

3. Verify API Health

curl -s http://localhost:5174/api/health | python3 -m json.tool

4. Test Core Functionality

Log in to the web UI at http://localhost:5173
Verify existing transcripts are accessible
Search for a known transcript to confirm OpenSearch is working
Upload a short test file to verify the transcription pipeline

5. Check Version

Confirm the UI footer or API response shows the expected version number.

Common Upgrade Issues

Container Fails to Start

# Check logs for the failing service
docker compose logs <service-name> --tail=100

# Common fix: recreate the container
docker compose up -d --force-recreate <service-name>

Migration Lock Timeout

If the backend hangs on startup waiting for a migration lock:

# Check for stuck advisory locks in PostgreSQL
docker compose exec postgres psql -U postgres opentranscribe -c "SELECT * FROM pg_locks WHERE locktype = 'advisory';"

# Restart the backend
docker compose restart backend

Model Compatibility

New versions may require updated AI models. If transcription fails after upgrading:

# Clear the model cache to force re-download
rm -rf ${MODEL_CACHE_DIR:-./models}/huggingface/hub/
docker compose restart celery-worker

New Environment Variables

If the backend logs show warnings about missing configuration:

# Compare your .env with the latest template
diff .env .env.example

# Add any missing variables from .env.example to your .env

OpenSearch Index Incompatibility

If search stops working after an upgrade:

# Check OpenSearch health
curl -s http://localhost:5180/_cluster/health | python3 -m json.tool

# If indices need rebuilding, use the Admin UI "Reindex All" function
# Or via API:
curl -X POST http://localhost:5174/api/admin/reindex -H "Authorization: Bearer <token>"

Permission Errors on Model Cache

After upgrading, the container user (UID 1000) may not have access to cached models:

# Fix permissions
./scripts/fix-model-permissions.sh

# Or manually
sudo chown -R 1000:1000 ${MODEL_CACHE_DIR:-./models}/

Pre-Upgrade Checklist​

Standard Upgrade Process​

Using opentr.sh (Recommended)​

Manual Upgrade​

Upgrading to a Specific Version​

Database Migrations​

How Migrations Work​

Current Migration Chain​

What to Do if Migrations Fail​

Rolling Back​

Reverting to a Previous Version​

Major Version Upgrades​

Embedding Migration (v3 to v4)​

Other Major Upgrade Considerations​

Verifying the Upgrade​

1. Check Service Health​

2. Check Backend Logs​

3. Verify API Health​

4. Test Core Functionality​

5. Check Version​

Common Upgrade Issues​

Container Fails to Start​

Migration Lock Timeout​

Model Compatibility​

New Environment Variables​

OpenSearch Index Incompatibility​

Permission Errors on Model Cache​