CCD SuiteDocs

Upgrades

./ccd upgrade is the safe upgrade path. It takes a snapshot, pulls the new images (or rebuilds), replays migrations, recreates app services, and polls health.

Usage

./ccd upgrade                       # rebuild local source (CCD_VERSION unchanged)
./ccd upgrade v1.1.0                # pin to a published tag, with backup
./ccd upgrade v1.1.0 --yes          # scripted (no confirmation)
./ccd upgrade dev --skip-backup     # dev iteration, no backup

What it does

  1. Plan — prints current → target versions and whether a backup will run. Prompts for confirmation unless --yes.
  2. Pre-upgrade backup — calls ./ccd backup create (unless --skip-backup). This is the rollback artifact.
  3. Rewrites CCD_VERSION in .env. If the line exists, replace; else append with a # Set by ccd upgrade on <UTC> header.
  4. Pulls or builds —
    • If target is dev: rebuilds the four CCD app service images locally via docker compose build.
    • Else: docker compose pull for the published images. If pull fails (gap in the release feed, registry down), falls back to a local build so you're not stranded.
  5. Replays migrations — docker compose up -d db-migrate. db-migrate is idempotent: it checks the migration ledger and only applies SQL files that haven't been recorded.
  6. Recreates app services — docker compose up -d web api-gateway ai-services worker. Compose stops the old containers and starts new ones with the new image tag.
  7. Health probe — polls http://localhost:${CCD_PORT}/api/health for up to 3 minutes. On timeout, points you at the three most-common-cause services for docker compose logs --tail=50 investigation.

Rollback

Two-step:

# 1. Restore the pre-upgrade backup (created in step 2 above)
./ccd backup restore ./backups/ccd-backup-<pre-upgrade-ts>.tar.gz --yes

# 2. Set CCD_VERSION back to the old tag and recreate
sed -i 's|^CCD_VERSION=.*|CCD_VERSION=v1.0.0|' .env   # or whatever the old version was
docker compose up -d --force-recreate web api-gateway ai-services worker

The data restore + image tag flip together return you to the pre-upgrade state.

What's not upgraded

./ccd upgrade only touches the four CCD app services. The data plane (Supabase OSS + Kong + Ollama) is pinned at fixed image tags in docker-compose.yml. Bumping them is an explicit edit:

# Example: bumping Postgres
db:
  image: supabase/postgres:15.6.1.143   # ← edit this line

Then docker compose pull && docker compose up -d. Major version bumps of Postgres (15 → 16) require a pg_upgrade workflow not covered by ./ccd upgrade — take a backup, follow Supabase's migration guide.

CI publishing

For published image tags (anything other than dev) to actually work, the CCD release pipeline builds + pushes the ccd-{web,worker,api-gateway,ai-services} images to the licensed CCD container registry (registry.ccdsuite.com) on each release tag. Your licence key authenticates the pull.

Tracking releases

CCD-Suite follows SemVer. Release notes live in the changelog. Subscribe to the release mailing list from your account for email notifications.