Skip to main content

Upgrading

How to upgrade DaoFlow to a new version.

CLI Upgrade​

The recommended path is the CLI because it preserves the install's selected workflow profile:

daoflow upgrade --yes

Lean upgrades keep only the base services active. Temporal upgrades start the Temporal services, wait for cluster health, restart DaoFlow, and verify that its Temporal worker reconnects before the command reports success.

Docker Compose Upgrade​

# Pull the latest image
docker compose pull

# Restart with the new version
docker compose up -d

# Check process health and startup readiness
curl http://localhost:3000/health
curl http://localhost:3000/ready

These manual commands use the profile values already stored in .env. For a Temporal install, start and verify Temporal before restarting DaoFlow:

docker compose --profile temporal pull
docker compose --profile temporal up -d temporal
docker compose --profile temporal exec -T temporal \
  temporal operator cluster health --address temporal:7233
docker compose --profile temporal up -d --remove-orphans daoflow

DaoFlow automatically runs required database migrations before the HTTP server starts accepting traffic. In production, a migration failure stops startup by default instead of serving requests against an incompatible schema.

If you want to run migrations as an explicit preflight without starting the web server:

docker compose run --rm -e DAOFLOW_RUN_MIGRATIONS_ONLY=true daoflow

Use DAOFLOW_ALLOW_START_WITH_MIGRATION_FAILURE=true only as an emergency operator bypass for an ordinary migration execution failure. It never bypasses a migration-lineage mismatch or a previously recorded failed migration. With that flag set, the process may continue in the limited cases where bypass is allowed, but /ready stays unavailable and the container healthcheck remains unhealthy.

When DaoFlow reports a previously failed migration, first repair the underlying database or migration problem. Then run one explicit retry as a migration-only preflight:

docker compose run --rm \
  -e DAOFLOW_RUN_MIGRATIONS_ONLY=true \
  -e DAOFLOW_RETRY_FAILED_MIGRATION=true \
  daoflow

Do not leave DAOFLOW_RETRY_FAILED_MIGRATION enabled. If the retry fails, DaoFlow records the failure again and blocks later restarts before repeating the same schema change.

Checking Status And Version​

# Via API status
curl http://localhost:3000/trpc/health | jq '.result.data.json'

# Via CLI
daoflow --cli-version

Backup Before Upgrading​

Always back up your database before major upgrades:

docker compose exec postgres pg_dump -U daoflow daoflow > backup-$(date +%Y%m%d).sql

Rollback​

If an upgrade fails:

# Stop the new version
docker compose down

# Restore the database backup
docker compose up -d postgres
docker compose exec -T postgres psql -U daoflow daoflow < backup-20260315.sql

# Start the previous version
docker compose up -d

Version Pinning​

For production stability, pin to a specific version:

services:
  daoflow:
    image: ghcr.io/daoflow-dev/daoflow:v0.1.0 # pinned

Changelog​

See the GitHub Releases for what changed in each version.