Skip to content
LabTether

Upgrading

LabTether upgrades are designed to be low-drama: pull new images, restart, and migrations run automatically. But like any infrastructure change, a little preparation goes a long way.

Upgrade paths

How you upgrade depends on how you installed LabTether.

Repo-checkout install (.env.deploy)

./scripts/upgrade-compose.sh --version v2026.1

This updates LABTETHER_VERSION in your .env.deploy, pulls the published release images, and recreates the deploy stack. One command, done.

Release artifact install

docker compose -f docker-compose.deploy.yml pull
docker compose -f docker-compose.deploy.yml up -d

If you fetched a newer release artifact with updated image references, swap in that file before running pull and up -d.

Before you upgrade

  1. Confirm current health. Check that nodes are connected, no critical incidents are active, and the system is stable.
  2. Back up. make db-backup at minimum. For critical environments, snapshot your VM or volume too.
  3. Read the release notes. Check for migration notes or breaking changes specific to the version you are upgrading to.
  4. Schedule a window. Upgrades are fast, but agents may briefly reconnect, and the console is down for a few seconds during restart.

After upgrading

Migrations run automatically as part of startup. Once the stack is back up:

  1. Health endpoint — confirm the API is responding:
docker compose -f docker-compose.deploy.yml ps

  1. Console loads — open the web console and verify login works.

  2. Nodes connected — check that your fleet shows connected status. Agents reconnect automatically after a hub restart, but it may take a heartbeat interval.

  3. Smoke test critical workflows:

    • Open a terminal session
    • Start a desktop session
    • Check the alerts and incidents pages
    • Verify connector sync is running

  4. Run setup diagnostics:

make setup-doctor
  1. Monitor for 15-30 minutes. Watch logs, error rates, and agent reconnect behavior. Most post-upgrade issues surface within this window.

Rolling back

If something goes wrong:

Repo-checkout: Set LABTETHER_VERSION back to the previous version in .env.deploy and rerun:

./scripts/upgrade-compose.sh --version <previous-version>

Release artifact: Restore the previous release artifact file and rerun:

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

If the database migration has already run, you may need to restore from your pre-upgrade backup. This is why the backup step is not optional.

Migration notes

Database migrations run automatically on startup and should be transparent. A few things to be aware of:

  • Read release-specific notes before upgrading. Some versions include migration steps that require attention — the release notes will call these out explicitly.
  • Migrations run exactly once per target environment. The migration system tracks which migrations have been applied.
  • Keep backups before running migrations. Migrations are forward-only — there is no built-in rollback for schema changes.
  • Schema mismatch errors after startup usually mean a migration failed partway through. Restore from backup, check the migration logs, and retry. Do not run the hub against a partially-migrated database.

Tip: If you manage multiple environments (dev, staging, production), upgrade dev first. Let it run for a day. Then staging. Then production. The incremental cost is low, and catching a migration issue in dev is vastly preferable to catching it in production.