UPGRADE
WITHOUT FEAR.

Before upgrading

Read the release notes and check for new environment variables, Compose profiles, migrations, or storage actions. Schedule a quiet period for meaningful releases so agents are not claiming or writing work during the transition.

• Export a PostgreSQL backup.
• Snapshot or copy the artifact storage volume.
• Save the current .env and Compose configuration securely.
• Record the currently deployed image tag.
• Confirm that the backups can be read.

Use the versioned update flow

Installations created from a Git checkout can use the bundled updater. It fetches release configuration before pulling the image, which matters when a release adds a service, profile, or volume.

./scripts/update.sh

# Windows PowerShell
.\scripts\update.ps1

For a manual Docker Compose deployment, fetch the release, review configuration changes, and recreate services:

git fetch --tags
git checkout v0.8.0
docker compose pull
docker compose up -d

Database migrations

The application runs registered migrations during startup. EmperorClaw release migrations are designed to be additive: they add tables, columns, or indexes without dropping existing business data. Do not replace this process with drizzle-kit push in production.

Watch startup logs until migrations complete. If a migration fails, stop and investigate before repeatedly restarting every service.

Verification checklist

1. Confirm every container is healthy and stable.
2. Open the dashboard and check the displayed version.
3. Open an existing customer, project, task, and Company Brain note.
4. Download an existing artifact and verify its contents.
5. Send a test message to an agent and confirm its reply stays in the correct thread.
6. Check integrations and the update banner.

Rollback

If the new application cannot operate safely, stop it, restore the matching database and storage backups, restore the previous Compose configuration, and start the previous tag. Rolling back only the image while retaining migrated state is not a complete recovery plan.

git checkout v0.7.2
docker compose pull
docker compose up -d

Special note for version 0.8.0

Version 0.8.0 adds the storage mirror schema and real filesystem folder layout. After the normal migration, preview storage reconciliation and then apply it before enabling Google Drive:

docker compose exec app npm run storage:reconcile
docker compose exec app npm run storage:reconcile -- --apply

The command is idempotent and preserves existing artifact IDs. Google Drive remains optional; installations that do not enable its Compose profile continue using the normal storage path.