Skip to main content

Upgrading Chaos Cypher

Chaos Cypher ships as a Docker image plus the Python CLI. This page covers tag-to-tag upgrades, schema migrations, and recovery from a failed upgrade.

TL;DR​

# all-in-one
docker compose pull && docker compose up -d

# multi-container dev
make docker-down && git pull && make docker-up

Cortex runs alembic upgrade head on startup before serving any request.

Pre-upgrade checklist​

  1. Take a backup: chaoscypher backup create --output backups/before-upgrade.ccx.
  2. Read the changelog for breaking changes between your tag and the target tag.
  3. Verify disk space — migrations may rewrite tables.

Upgrade flow (all-in-one)​

  1. Pull the new image: docker pull ghcr.io/chaoscypherinc/chaoscypher:<tag> (when published).
  2. Stop the old container: docker compose down.
  3. Start the new: docker compose up -d.
  4. Watch the logs: docker compose logs -f cortex.
    • You'll see alembic.runtime.migration lines as Alembic walks pending revisions.
    • When you see Application startup complete, the upgrade succeeded.
  5. Verify health: curl http://localhost/api/v1/health.

Upgrade flow (multi-container dev)​

make docker-down
git pull origin main
make install     # uv sync --all-packages --extra dev
make docker-up

Rollback​

If migrations fail or the new tag is unhealthy:

  1. Stop cortex: docker compose stop cortex.
  2. Restore the pre-upgrade backup: chaoscypher backup restore backups/before-upgrade.ccx.
  3. Pull the previous tag (or check out the previous commit): docker pull ghcr.io/chaoscypherinc/chaoscypher:<previous-tag>.
  4. Start: docker compose up -d.

Alembic supports targeted downgrades (alembic downgrade -1), but the recommended path is restore-from-backup.

Operator-grade upgrade: chaoscypher upgrade​

chaoscypher upgrade runs alembic upgrade head against the configured database. Use it when you need to apply pending migrations without restarting the full stack — for example, after pulling a new package version in a dev environment or after restoring a backup.

# These are equivalent — pick whichever fits your workflow:
chaoscypher upgrade
# or
uv run alembic upgrade head

Per ADR-0006, Alembic is the authoritative migration tool. Cortex runs the same alembic upgrade head on startup, so chaoscypher upgrade is useful when you need to trigger migrations outside the normal startup path.

Breaking-change markers​

Major version bumps may require manual steps. The changelog flags these with BREAKING:. Read those entries before pulling a new major.

See also: