Rollback Playbook¶

Decision: Rollback vs Hotfix?¶

Situation	Strategy
Broken deploy, previous version was stable	Rollback
Bug found but previous version also had issues	Hotfix
Data migration was applied (DB schema changed)	Hotfix (rollback may lose data)
Security vulnerability in the new release	Rollback + hotfix in parallel

Rollback Procedure — Docker Compose¶

1. Identify the last known good version¶

# List available tags
docker image ls ghcr.io/scub-france/docling-studio --format '{{.Tag}}' | sort -V

# Or check GitHub releases
gh release list --repo scub-france/Docling-Studio

2. Pin the image to the previous version¶

Edit docker-compose.yml or docker-compose.override.yml:

services:
  backend:
    image: ghcr.io/scub-france/docling-studio:0.2.0-remote  # pin to last good
  frontend:
    image: ghcr.io/scub-france/docling-studio:0.2.0-remote

3. Restart¶

docker compose down
docker compose up -d --wait

4. Verify¶

curl -s http://localhost:3000/api/health | jq .
# Confirm version matches the rolled-back version

5. Communicate¶

Notify the team that a rollback was performed
Open an issue describing the failure
Link the failed release and the rollback commit

Rollback Procedure — Hugging Face Space¶

Use git revert on the HF Space repo to revert to the previous commit
Or re-upload the previous version: huggingface-cli upload <space-id> . . --repo-type space --revision <previous-commit>
Verify the app loads correctly

Database Considerations¶

Docling Studio uses SQLite with a file-based database. Key points:

No schema migrations are applied automatically — the schema is created on first run
If a new release adds columns, rolling back may cause "unknown column" errors
Before deploying a release that changes the DB schema: back up the SQLite file

# Backup before deploy
cp data/docling-studio.db data/docling-studio.db.bak-$(date +%Y%m%d)

# Restore after rollback
cp data/docling-studio.db.bak-YYYYMMDD data/docling-studio.db

Post-Rollback¶

Keep the rollback in place until the root cause is identified
Fix the issue on a hotfix/* branch
Re-run the release audit on the fix
Re-deploy following the deployment checklist