Upgrades

This page describes the procedure for upgrading CleverThis to a new version. CleverThis follows semver. Patch releases (x.y.Z) are safe to apply without reading release notes. Minor releases (x.Y.0) may include new env vars or configuration changes. Major releases (X.0.0) include breaking changes and require reading the migration guide.

Before upgrading

1. Read the release notes for the target version at github.com/cleverthis/cleverthis/releases. Note any new required environment variables or breaking changes.
2. Back up your database before every upgrade. See Backup & Restore.
3. Test in staging first if you have a staging environment.

Docker Compose upgrade

# 1. Pull the new images
docker compose pull

# 2. Apply any new environment variables to .env

# 3. Restart the stack (api and webapp)
docker compose up -d --no-deps api webapp

# 4. Run database migrations
docker compose exec api alembic upgrade head

# 5. Verify the upgrade
curl https://your-domain.com/health
docker compose logs --tail=50 api

If the migration fails or the health check returns non-200, roll back immediately (see below).

Kubernetes upgrade

# 1. Update the Helm repo
helm repo update

# 2. Check what's changing
helm diff upgrade cleverthis cleverthis/cleverthis \
  --namespace cleverthis \
  --values values.yaml

# 3. Apply the upgrade
helm upgrade cleverthis cleverthis/cleverthis \
  --namespace cleverthis \
  --values values.yaml

# 4. Watch the rollout
kubectl rollout status deployment/cleverthis-api -n cleverthis

Rolling back

# Docker Compose: pull the previous version tag
docker compose pull  # after reverting docker-compose.yml to old image tags
docker compose up -d --no-deps api webapp

# Kubernetes
helm rollback cleverthis --namespace cleverthis

Database migrations cannot be automatically rolled back. If a migration introduced a schema change that is incompatible with the old version, restore from backup instead.

Coming soon

Zero-downtime migration procedures for databases with large tables are being documented.