⚡NestFleetDocs

Upgrading

NestFleet follows semantic versioning. Minor and patch releases are backward-compatible — upgrading is a pull, rebuild, and restart. Major releases include a migration guide in the release notes. Always take a backup before upgrading.

Always back up before upgrading. Run bash scripts/backup.sh and verify the backup file exists in backups/ before proceeding. See the Backup & Restore guide.

Standard upgrade procedure

1. Pull the latest code

git pull origin main

If you track a specific release tag rather than main, fetch and check out the new tag:

git fetch --tags
git checkout v1.5.0

2. Rebuild the Docker images

docker compose -f docker-compose.prod.yml build

This rebuilds the api, worker, and console images from the updated source. The postgres and caddy images are pulled from their registries and do not need a build step.

3. Apply database migrations

Migrations run automatically on API startup. You do not need to run any migration command manually. When the api container starts, it applies all pending migrations from src/infra/db/migrations/ in order before accepting traffic. This is safe because migrations are idempotent — already-applied migrations are skipped.

4. Restart the stack

docker compose -f docker-compose.prod.yml up -d

Docker Compose performs a rolling restart — it stops and replaces each container with the new image while keeping the PostgreSQL data volume intact. The --detach flag returns immediately; use docker compose logs -f api to watch the startup and migration output.

5. Verify health

curl https://your-domain/health

Expected response after a successful upgrade:

{"status":"ok","db":"ok"}

Also log in to the console and confirm your data is intact. Check the API logs for any warnings from the migration runner.

Rollback procedure

If the new version has a critical regression, you can roll back to the previous release. The rollback process restores both the code and the database to the pre-upgrade state.

Rolling back is only safe if the migration is reversible and you have a clean backup from before the upgrade. Some migrations (e.g. dropping a column) cannot be undone by simply reverting the code. Always consult the release notes for the version you are rolling back from.

  1. Stop the stack:
    docker compose -f docker-compose.prod.yml down
  2. Restore the database from your pre-upgrade backup (see Backup & Restore).
  3. Check out the previous release tag:
    git checkout v1.4.2
  4. Rebuild and restart:
    docker compose -f docker-compose.prod.yml build
docker compose -f docker-compose.prod.yml up -d
  5. Verify health and open a GitHub issue describing the regression so it can be fixed in the next release.

Checking the installed version

curl https://your-domain/health | jq .version

The health endpoint includes the running version string. Compare this against the latest release on the GitHub Releases page.