Upgrade your Chef Habitat On-Prem Builder deployment

Chef Habitat On-Prem Builder services don’t upgrade automatically. To upgrade the services, use the uninstall script to stop, unload, and remove them.

Note

The uninstall script doesn’t remove user data, so you can uninstall and reinstall the Habitat Builder services without losing data.

Before you begin

If you’re upgrading to a Habitat Builder version dated 20260728 or later from an earlier version and you’re using MinIO and PostgreSQL to store data, back up your /hab/svc directory prior to upgrading.

This release includes major version upgrades of MinIO and PostgreSQL and upgrading to this release triggers an automatic data migration, which can take several minutes to complete.

If the upgrade fails, you can restore your backed-up data and roll back to an earlier Habitat Builder version.

If you store data on your own external PostgreSQL or S3-compliant storage, then you don’t need to worry about upgrading the MinIO or PostgreSQL packages installed with Habitat Builder.

Upgrade Chef Habitat On-Prem Builder

To upgrade Chef Habitat On-Prem Builder, follow these steps:

Clone a fresh copy of the habitat-sh/on-prem-builder repository on the computer running Habitat On-Prem Builder.
Confirm your bldr.env file has a valid HAB_AUTH_TOKEN and set BLDR_CHANNEL to on-prem-base.
See the bldr.env.sample file for an example.
Uninstall all Habitat Builder services by running the uninstall script:
```
sudo ./uninstall.sh
```
After the services are uninstalled, reinstall them by running the install.sh script:
```
./install.sh
```
Optional: Follow the supervisor logs to monitor the migration progress. Services may be unavailable for a few minutes after install.sh completes, particularly when a data migration is triggered when updating builder-minio or builder-datastore.
To follow the logs, run the following command:
```
journalctl -fu hab-sup
```
While the migration runs, it is common to see a large number of entries similar to:
```
Aug 14 15:11:58 ip-172-31-38-141 hab[121787]: [3.4K blob data]
```
The migration is typically finished once you see a final entry like:
```
Aug 14 15:12:14 ip-172-31-38-141 hab[121787]: builder-minio.default hook[post-run]:(HK): Minio bucket is up to date.
```

Roll back an upgrade

If an upgrade to a version dated 20260728 or later fails, and you backed up your /hab/svc directory beforehand, you can roll back to the latest on-prem version prior to 20260728:

Uninstall all Habitat Builder services by running the uninstall script:
```
sudo ./uninstall.sh
```
Restore your backed up /hab/svc directory.
In your bldr.env file, set BLDR_CHANNEL to on-prem-stable.
Reinstall the services by running the install.sh script:
```
./install.sh
```

Binlink Chef Habitat version 1.6:

sudo hab pkg install core/hab --channel stable -bf

Restart the hab-sup systemd service:
```
sudo systemctl restart hab-sup
```