Upgrade Guide

Docker Compose Upgrade

1. Update the version in .env

   # Set to the version you want (e.g. 0.11.3)
   BREEZE_VERSION=0.11.3

2. Pull and restart

   docker compose pull
   docker compose up -d

   This pulls the new API, web, and binaries images and restarts all services. Database migrations run automatically on API startup when AUTO_MIGRATE=true (the default).

   Expected downtime: Typically 5—15 seconds while containers restart. If the new version includes database migrations, the API container will take additional time to apply them before accepting traffic — usually under 60 seconds for routine schema changes, but potentially several minutes for large data migrations. Agents continue running independently during this window and reconnect automatically.

3. Verify

   # Check API health
   curl -s https://breeze.yourdomain.com/health | jq .version
   
   # Check agent version (on the device)
   breeze-agent version

Tip

The binaries-init container uses pull_policy: always, so docker compose up -d automatically pulls the latest binaries image and refreshes the volume — no manual steps needed.

Agent Updates

Agents update themselves automatically. On each heartbeat (~60s), the API checks if a newer version is available and signals the agent to upgrade. The agent:

1. Downloads the new binary and verifies its SHA-256 checksum
2. Backs up the current binary
3. Replaces the executable and restarts the service
4. Rolls back automatically if the new binary fails to start

The binary source depends on your BINARY_SOURCE setting:

Mode	Agent downloads from
github (default)	GitHub Releases CDN
local	Your API server (or S3 if configured)

See Binary Distribution for details.

Migration Failure Recovery

If the API container fails to start after an upgrade due to a migration error, follow these steps:

1. Check the container logs to identify the failing migration.

   docker compose logs api --tail 100

   Look for lines starting with [auto-migrate]. Common failure messages include:

   • Migration checksum mismatch — a previously applied migration file was modified. This should never happen in normal operation.
   • SQL errors during a specific migration file (e.g., constraint violations, missing columns).

2. Do not manually edit migration files. Migrations are tracked by checksum. Modifying a previously applied migration will cause all future startups to fail.

3. Fix and restart. The most common causes and resolutions:

   • Incompatible extension (e.g., TimescaleDB not installed): Install the required extension and restart.
   • Permissions issue: Ensure the database user has sufficient privileges.
   • Data conflict: Manually resolve the conflicting data in the database, then restart the API container.

   docker compose restart api

4. If unrecoverable, restore your database from a pre-upgrade backup and re-attempt the upgrade after resolving the underlying issue.

Caution

Migrations run inside a transaction. If a migration fails partway through, the transaction is rolled back and no partial changes are applied. The API will not start until all migrations succeed.

Zero-Downtime Upgrades

For production deployments where any downtime is unacceptable, you can perform a blue-green upgrade using two parallel Compose stacks:

1. Deploy the new version alongside the old one. Use a separate Compose project name or directory with the new BREEZE_VERSION and point it at the same database and Redis.

   COMPOSE_PROJECT_NAME=breeze-new BREEZE_VERSION=0.12.0 \
     docker compose -f docker-compose.yml -f docker-compose.override.yml up -d

2. Wait for migrations and health check. The new API container applies any pending migrations on startup. Once the health endpoint returns the expected version, the new stack is ready.

   curl -s http://localhost:NEW_PORT/health | jq .version

3. Switch traffic. Update your reverse proxy (Caddy, nginx, Cloudflare tunnel) to route traffic to the new stack.

4. Tear down the old stack. Once traffic is fully migrated, stop the old containers.

Rolling Back

1. Revert the version

   # In .env
   BREEZE_VERSION=0.11.2

2. Pull and restart

   docker compose pull
   docker compose up -d

Danger

Database migrations are forward-only. If the newer version ran a migration, reverting the API version may cause schema mismatches. Restore from a database backup if needed.

Checking Versions

# API version
curl -s https://breeze.yourdomain.com/health | jq .version

# Agent version (on the device)
breeze-agent version

# Docker image versions
docker compose images

Pre-Release Testing

You can test a release candidate before making it available to users:

1. Tag a prerelease

   git tag v0.11.3-rc.1 && git push --tags

   CI builds all images but does not tag them as latest.

2. Deploy the RC locally

   # In .env
   BREEZE_VERSION=0.11.3-rc.1
   
   docker compose pull
   docker compose up -d

3. Sync agents to the RC using the sync-github endpoint. This fetches the release assets from GitHub and registers them in the Breeze database so agents know a new version is available.

   curl -X POST "https://your-domain/api/v1/agent-versions/sync-github?version=v0.11.3-rc.1" \
     -H "Authorization: Bearer <api-key>"

   The response includes the version that was synced and the list of platform/architecture targets that were registered:

   {
     "version": "0.11.3-rc.1",
     "synced": ["agent:linux/amd64", "agent:macos/arm64", "agent:windows/amd64", "helper:windows/amd64"]
   }

   Agents will pick up the new binary on their next heartbeat (~60 seconds). Omit the ?version= parameter to sync the latest stable release instead of a specific version. This endpoint requires system-level (admin) authentication.

4. Test, then promote

   git tag v0.11.3 && git push --tags

   This pushes latest tags — all users get the update.