nano SIEM
Releases

Upgrade a self-hosted deployment

Supported in:Self-hosted

Check which nano version you run, then upgrade an Open or Self-run deployment on one host, several hosts or Kubernetes to the latest release.

Upgrade to the latest release to get its fixes. When the release notes say a version includes security fixes, upgrade as soon as you can.

Every upgrade runs the new schema migrations first and starts the new app services only after they succeed. Migrations are forward-only: you can't downgrade across a schema change. Roll forward instead.

Before you upgrade

  1. Check your current version. In nano, open the user menu at the bottom of the left rail; it shows nano v<version>. Your deployment's page in app.nano.rs shows the version it last reported.
  2. Read the release notes for every version between yours and the latest. They call out any required action.
  3. Back up PostgreSQL (rules, cases, users, settings) and keep a copy of your .env or chart secret. Losing the encryption key makes every stored credential unrecoverable.

Single host (Docker Compose)

Self-run

nano Self-run pulls its images from the registry. You upgrade with the new release's installer bundle, nano-compose-enterprise-<version>.tar.gz, with its .sha256 and .sha256.sig. That is the usual path. From v2.0.29 you can also upgrade a registry install offline with the image bundle, nano-<version>-enterprise.tar, the one air-gapped installs use. The bundle names nano's images after nano's own registry repository. When they load, after their digests verify, the upgrade also tags the same signed images with your install's NANO_IMAGE_PREFIX, for example the customer registry an install from app.nano.rs uses. The dry run reports this as bundle-image-names and refuses, before any host changes, a bundle whose image names it can't match to your install. Extract the installer package first in this case too, then pass the image bundle to --bundle as it is. Don't unpack or rebuild it. Before v2.0.29, an image-bundle upgrade of a registry install failed at rollout:migration with "No such image".

From v2.0.10 or later (your install runs v2.0.10 or a later release):

  1. Download and verify the new bundle. See Get the bundle. Keep the three files together, for example in /srv/nano/releases/.

  2. Make sure your backup key exists. See Back up.

  3. Unpack the bundle over your install directory, ~/nano. It holds no .env and no data, and nothing restarts yet:

    tar -xzf /srv/nano/releases/nano-compose-enterprise-<version>.tar.gz --strip-components=1 -C "$HOME/nano"
  4. Log in to the registry with a fresh pull credential; it lasts one hour. Upgrading to v2.0.30 or later with an online license, skip this step: scripts/nano upgrade logs in with the license values in .env, in a temporary Docker configuration that leaves your ~/.docker untouched.

  5. Dry-run the upgrade:

    cd "$HOME/nano"
    scripts/nano upgrade --bundle /srv/nano/releases/nano-compose-enterprise-<version>.tar.gz \
      --backup-key-file /secure/nano-backup/operator.pem --dry-run
  6. When every check passes, run the same command without --dry-run. If you logged in by hand, log out of the registry: docker logout us-central1-docker.pkg.dev.

scripts/nano upgrade verifies the bundle's signature and reads the image digests, migrations and upgrade requirements from inside it. It takes a backup, keeps your existing .env and secrets, pulls each image by its signed digest and runs the migrations. Then it recreates the services that run a new image and checks that a test event becomes searchable. Finally it compares SIEM Health findings with the report from before the upgrade. If it fails, the previous version keeps running. If it stops partway, fix the cause (often an expired registry login) and run it again with --resume. It refuses to switch an install between open core and Self-run.

From v2.0.13:

  • It also recreates every service whose mounted configuration file changed, not only those with a new image.
  • Before it compares SIEM Health findings, it waits for a report made after the upgrade, up to 600 seconds (NANO_UPGRADE_SIEM_HEALTH_WAIT_SECONDS). The first report runs about 5 minutes after the API starts. If none arrives, it prints a warning and records that it didn't run this check.
  • From v2.0.31, a new ClickHouse memory-limit or dictionary-update error that wasn't seen in the 24 hours before the upgrade, happened only during the rollout and has been quiet for 5 minutes doesn't fail that comparison. It is listed in the summary instead. After a failed comparison, --resume restarts nano-jobs to get a fresh report and waits for it.
  • It prints each step as it happens, also when you run it over a plain ssh: a ==> <time> <step>: started line and a done in <N>s line. Every step is also recorded in ~/nano/upgrade-journal/.

From v2.0.9 or earlier: that release's scripts/nano upgrade can't use the installer bundle, so upgrade to v2.0.10 by running the installer again. Take a backup, download and verify the v2.0.10 bundle, unpack it over ~/nano, log in to the registry, and run your install command again. The installer keeps .env, runs the migrations and restarts nano on v2.0.10. On several hosts, run each host's install command in turn, in the order High availability gives.

Open

cd ~/nano
git pull
bash install.sh

See Install with Docker Compose for what the installer does.

Several hosts

The v2.0.10 to v2.0.11 known issue above (fixed in v2.0.12) applies to several hosts too; see High availability for the per-server installer rerun if you upgrade to v2.0.11 itself. Before the first scripts/nano upgrade on several hosts, set up SSH from the first app server, the drain and rejoin hooks and the load balancer's admin socket, as High availability lists. Then unpack the new installer bundle over ~/nano on every server, log in to the registry on every server (not needed when upgrading to v2.0.30 or later with an online license: each server logs in with the license values in its own .env), then run scripts/nano upgrade once, from ~/nano on the first app server, with the bundle and the same reviewed inventory you installed with. Dry-run first. It upgrades one server at a time, in order, and checks health between them. It takes each app and ingest server out of the load balancer before restarting it, and puts it back after. From v2.0.13 it also renders each server's configuration again from the new bundle and your inventory, shows the difference in the dry run, and recreates every service whose configuration changed.

See High availability for the full command, and for upgrading from v2.0.9 or earlier, where you run each server's installer again in order instead.

Kubernetes (Helm)

Log in to the registry with a fresh credential and pull the new chart. Then upgrade with the same -f files as the install, in the same order, plus --wait --timeout 20m. This example matches an HA install on EKS:

export NANO_VERSION=<new version>
rm -rf nano && helm pull oci://us-central1-docker.pkg.dev/nano-rs/nanosiem-customer/charts/nano \
  --version "$NANO_VERSION" --untar
helm upgrade nano ./nano -n nano --wait --timeout 20m \
  -f nano/values-customer-images.yaml -f nano/values-small.yaml -f nano/values-aws.yaml \
  -f values-12gb.yaml -f values-12gb-ha.yaml -f my-values.yaml

Don't use --reuse-values: it ignores the new chart's defaults, and with charts 2.0.12 and earlier it also kept the old images. If you no longer have the -f files, use --reset-then-reuse-values -f nano/values-customer-images.yaml. See Upgrades.

Migrations run as a pre-upgrade hook before any Deployment changes; if the hook fails, the previous version keeps serving. Always pass --wait --timeout 20m, because migrations wait for ClickHouse and --wait only reports success once the new pods are ready. Helm never upgrades CRDs, so apply a newer ClickHouse operator's CRDs first when the release notes say so. See Kubernetes (Helm), and Upgrade recovery if the upgrade fails.

Verify the upgrade

  • The user menu in nano shows the new nano v<version>.
  • The Update available banner is gone after the next license check-in (at most a day). The deployment page in app.nano.rs updates at the same time.
  • Search returns recent events and ingest is flowing.

Troubleshoot

The installer stops at the migration step

The app services keep running the previous version; nothing is half-applied. Fix the cause shown in the clickhouse-migrate output and run the installer again. If it fails again, contact support with the deployment ID, the version you are upgrading from and to, and the migration output.

The license is locked with "Upgrade required"

A Self-run install on a v2 release before v2.0.10 gets this lock at its next license check-in. Pushed ingest (HTTP, HEC, OTLP), search over stored data and scheduled detection rules keep running, and local admins can still sign in; SSO sign-in, pull collectors, cases, SOAR and AI stop until you upgrade. Upgrade as above; the upgraded install checks in when it starts and the lock clears. See Self-run.

The banner still shows after upgrading

The banner follows the license check-in, which runs once a day and at startup. Restart the API service, or wait for the next check-in.

What's next

On this page