Upgrade¶

An upgrade installs a newer release over the same install directory with that release's own install.sh. The installer keeps .env (apart from the one-time database password split), the license and every data volume, replaces the compose file and scripts, verifies and pulls the new images, migrates the database and restarts what changed. Each release is published at https://get.huitzo.com/self-hosted/<version>/ with its own RELEASE-NOTES.md.

The upgrade sequence¶

# pseudocode: operator sequence
1. Read the new release's RELEASE-NOTES.md
2. Back up                         /opt/huitzo/backup.sh
3. Download and verify             the new release's assets, pre-run check
4. Run the new install.sh          ./install.sh --pull-credentials pull-credentials.json
5. Check                           /health reports the new version, license still VALID
6. If something is wrong           restore the backup with the previous release

1. Read the release notes¶

RELEASE-NOTES.md names the version, the image digests and any step that release needs before or after the upgrade. If you skip releases, read the notes of every release in between.

2. Back up¶

Always take a full backup first. The database migrations of a new release are not reversed by installing an older one, so the backup is the rollback.

# pseudocode
/opt/huitzo/backup.sh --output /mnt/backups

backup.sh captures the database dump, every volume, .env and license/license.json (Backups).

3. Download and verify the new release¶

Download every asset of the new version into a new, empty directory and run the pre-run check: cosign verify-blob on SHA256SUMS with Huitzo's release identity, then sha256sum -c SHA256SUMS (Download, Pre-run check). Stop if either fails.

4. Run the new install.sh¶

# pseudocode: in the new release's download directory
./install.sh --pull-credentials pull-credentials.json

Run it with no other flags, or with --prefix if you installed somewhere other than /opt/huitzo. The installer reads the domain and TLS mode from the existing .env and refuses flags that contradict it. It:

1. checks the support matrix;
2. replaces docker-compose.yml, Caddyfile, .env.template, install.sh and backup.sh in the install directory, and never touches the license;
3. logs in to the registry for this run only, verifies the signature of every new image and pulls it;
4. splits a single HUITZO_DB_PASSWORD from an older release into per-role passwords, after stopping the backend, workers and beat and writing .env.bak; the application stays down, through the migrate run, until step 6 starts it again (Upgrading an install with one database password);
5. runs migrate, which applies the new release's database migrations;
6. recreates the services whose image or configuration changed (docker compose up -d) and waits for them to be healthy.

The first admin already exists, so that step is skipped.

5. Check¶

# pseudocode
curl -s https://<host>/health                 # "version" is the new release
curl -s https://<host>/api/v1/setup/status    # license.state still valid, every check passing

An upgrade never changes the license state on its own: the deployment ID and the license file are unchanged. Sign in and run a command from a Pack as a final check.

6. Roll back¶

If the new release misbehaves, restore the backup from step 2 with the release you upgraded from:

1. Stop the stack: docker compose --project-directory /opt/huitzo down.
2. Restore the backup into the install directory with the previous release's assets, following Restore. The database must come from the backup: an older release does not run on a database that a newer release has migrated. Use the backup's .env too: a release from before the password split reads only HUITZO_DB_PASSWORD.
3. Check as in step 5; /health reports the previous version.

Restoring the backup keeps the deployment ID, so the license stays valid (Deployment ID on restore). Work done between the backup and the rollback is lost; tell your Huitzo partner contact what failed.

Support and contacts¶

Related documentation¶

• Connected installation
• Operations
• License status and renewal