Upgrades & Backups

Overview

Controller upgrades are image upgrades: pull the new images and recreate the containers. Database migrations run automatically when the API starts, and your data volumes are kept. The Controller version is shown in Administration → Deployment Info, Platform Health and the dashboard's System Health panel.

Run all commands below from the deploy directory that contains your .env and docker-compose.yml.

Upgrade with upgrade.sh

upgrade.sh wraps the manual steps and adds a database backup and a health check:

./upgrade.sh 0.0.20     # upgrade to a specific version
./upgrade.sh            # prompts for the version

It performs these steps:

1. Pulls the target controller, admin-ui and crawler images.
2. Dumps the bundled database to backups/netstacks_v<current>_<timestamp>.sql.gz (the five most recent dumps are kept).
3. Sets NETSTACKS_VERSION in .env.
4. Runs docker compose up -d (only containers whose image changed are recreated).
5. Polls /health for up to two minutes and prints rollback steps if the API doesn't come up.

Upgrade Manually

1. Download a backup first (see below).
2. Edit .env and set NETSTACKS_VERSION to the new version. If you use latest, leave it as is — pull fetches the newest release.
3. Pull and recreate:

   docker compose pull
   docker compose up -d

4. Confirm the new version in Administration → Deployment Info, or with curl -k https://localhost:3000/health.

The internal TLS CA lives in the netstacks_data volume, so browsers and Terminal clients that already trust it don't need to re-trust anything after an upgrade.

Roll Back

1. Set the previous version in .env (NETSTACKS_VERSION=<old>).
2. Restore the pre-upgrade dump if the new version already migrated the database:

   gunzip -c backups/netstacks_v<old>_<timestamp>.sql.gz | \
     docker exec -i $(docker compose ps -q db) psql -U netstacks netstacks

3. Pull and start the old images:

   docker compose pull
   docker compose up -d

Back Up from the Admin Console

Administrators with the System Settings permission can download a full database backup at any time:

1. Open Administration → Deployment Info (/admin/system).
2. In the Database Management card, under Backup, click Download Backup.
3. Your browser downloads netstacks-backup-<timestamp>.sql. Store it off the Controller host.

The file is a plain SQL dump of the whole database — users, devices, profiles and their secrets (still encrypted), config backups, the discovery (crawler) schema, the knowledge base, plugin data and database roles. It uses --clean --if-exists so it can be restored over an existing database. Each backup is recorded in the audit log as system.backup.

Restore a Backup

1. Open Administration → Deployment Info.
2. Under Restore, choose a .sql file previously downloaded with Download Backup.
3. Click Restore and confirm in the Confirm Database Restore dialog. This overwrites all current data.

Restores are recorded in the audit log as system.restore.

What a Complete Backup Needs