Upgrade, rollback and backup

An upgrade only replaces images and deployment files. .env, state/machine-id and the gateway_state volume are kept, the license's host fingerprint does not change, and no reactivation is needed afterwards.

Always upgrade in the original install directory. Compose takes the project name from the directory name and names the volume <directory>_gateway_state, so a different directory means a new, empty volume.

Upgrade with the install command

For deployments installed with install.sh into /opt/rst-ai-copilot-for-zabbix. Before 2.0.2 the install directory was /opt/rst-zabbix-ai-copilot; when that directory holds a .env, the script keeps upgrading it in place.

Steps

1. Run the install command again. Add --version <x.y.z> for a specific version:

   curl -fsSL https://github.com/Reallysec/RST-AI-Copilot-for-Zabbix/releases/latest/download/install.sh | sudo bash

2. When deploy.sh asks whether to keep the existing .env, enter y.

3. When asked whether to recreate and start the containers, answer yes.

After the signature check, the script removes the old version's image archive from the directory, unpacks the new archive, loads the new images and restarts the containers.

Upgrade from 2.0.1 or earlier to 2.0.2

From 2.0.2 the archive, image and containers carry the new product name: archive RST-AI-Copilot-for-Zabbix-<version>.tar.gz, gateway image rst-ai-copilot-for-zabbix-gateway, containers rst-ai-copilot-for-zabbix-gateway and rst-ai-copilot-for-zabbix-caddy. Gateways on 2.0.1 or earlier cannot find the renamed archive, so an online update to 2.0.2 fails. Upgrade once by hand, either way:

• Upgrade with the install command. The script keeps using the old /opt/rst-zabbix-ai-copilot directory.
• Upgrade from the archive: unpack it into the existing install directory, run ./deploy.sh and keep .env.

Data volumes and the license binding are unchanged: volume names come from the install directory name and state/machine-id lives in that directory, so always upgrade in place. The old containers are replaced by containers with the new names. Online updates work as usual afterwards.

Upgrade from 2.0.0

From 2.0.1 on, Caddy Basic Auth is gone and the gateway's own sign-in page is used, with accounts managed on the Users page. The old Basic Auth account is no longer used, and CADDY_BASIC_AUTH_USER and CADDY_BASIC_AUTH_HASH can be removed from .env.

A 2.0.0 .env has no RST_ADMIN_PASSWORD_HASH. The administrator admin then only has the factory password, which works only from the gateway host itself; a browser sign-in returns 403. Both deploy.sh and rst-update.sh point this out when they finish. After the upgrade, in the install directory, run:

docker exec rst-ai-copilot-for-zabbix-gateway python -m backend.session_auth '<password>'

Write the output to RST_ADMIN_PASSWORD_HASH= in .env (every $ written as $$), run docker compose -f docker-compose.prod.yml up -d, and sign in as admin with that password.

Upgrade from the archive

Steps

1. Delete the old version's image archive from the install directory, then unpack the new archive into it:

   rm <install-dir>/RST-AI-Copilot-for-Zabbix-images-*.tar
   tar xzf RST-AI-Copilot-for-Zabbix-<new-version>.tar.gz --strip-components=1 -C <install-dir>
   cd <install-dir>
   sudo ./deploy.sh

2. When asked whether to keep the existing .env, enter y. When asked whether to recreate and start the containers, answer yes.

deploy.sh loads only the first image archive it finds in the directory, which is why the old one goes first.

Upgrade from Community

Every edition uses the same archive. An administrator imports a Professional or Enterprise license under Settings > License; no reinstall is needed, and data and the host fingerprint are kept. See License.

Online update

Prerequisites

• The gateway host can reach github.com and its download domains on 443. The release manifest and the archive come from GitHub Releases. Offline-activated hosts never check for updates.

Steps

1. In Settings, under Version and updates, look at Online update. The gateway checks once a day; you can also select Check now.

2. When it shows "Version … available", select Download and stage. The gateway checks the signed manifest and the SHA-256, then stages the archive in ./release/ in the install directory.

3. On the gateway host, in the install directory, run:

   sudo ./deploy/rst-update.sh

rst-update.sh does not trust what the gateway downloaded. On the host it verifies the signed manifest and the archive again with its embedded public key, then loads the image, replaces the compose files and Caddyfiles with the new version's copies (the old ones are kept as .bak), switches GATEWAY_IMAGE_TAG in .env and restarts the gateway. The upgrade succeeds if the container health check passes 3 times in a row within 120 seconds; otherwise it rolls back to the previous version automatically. .env and ./certs are never touched.

Content packs

A content pack is a signed set of prompts and templates, released separately from versions; applying one needs no restart. The gateway checks for updates once a day, and an administrator can also select Check now. Each check also looks on GitHub for a content pack newer than the active one and activates it as soon as its signature checks out.

To have an administrator activate packs by hand, set RST_CONTENT_AUTO_APPLY=0 in .env and recreate the gateway container; see Configuration reference. New packs are then only downloaded, verified and kept on the host, and an administrator activates one under Settings > Content pack by selecting Roll back to this version on it.

On an offline host, paste the content pack token under Import a content pack on the same card and select Verify and import. A bad signature or a version older than the active one is rejected. To go back to an older version kept on the host, select Roll back to this version on it.

Switch the image version by hand

Steps

1. Load the new image and edit .env:

   docker load -i RST-AI-Copilot-for-Zabbix-images-<new-version>.tar
   sed -i 's/^GATEWAY_IMAGE_TAG=.*/GATEWAY_IMAGE_TAG=<new-version>/' .env

   If .env has no GATEWAY_IMAGE_TAG line, append GATEWAY_IMAGE_TAG=<new-version>.

2. Run docker compose -f docker-compose.prod.yml up -d.

To roll back, set GATEWAY_IMAGE_TAG back to the previous version the same way. This product never changes data in Zabbix, so a rollback does not affect Zabbix.

What to back up

Hosts, problems, triggers and history in Zabbix are not backed up by this product. Alerts in the gateway are copies; if lost, they are polled again from Zabbix and only the AI summaries are gone.

Back up the gateway state

The backup and restore scripts use the gateway image to read and write the volume, so no extra image is needed; run them from the install directory.

Steps

1. In the install directory, run:

   bash scripts/backup.sh /backup/rst-copilot

2. Set the backup directory to mode 700: chmod 700 /backup/rst-copilot.

The script packs the gateway_state volume into gateway-state-<time>.tar.gz, copies state/machine-id to machine-id-<time>, and deletes backups in that directory older than 30 days (change it with RETENTION_DAYS). Without a directory it writes to ./backups. For the SSO deployment, prefix it with COMPOSE_FILE=docker-compose.sso.yml. To run it daily, add a cron entry:

0 2 * * * cd /opt/rst-ai-copilot-for-zabbix && bash scripts/backup.sh /backup/rst-copilot >> /var/log/rst-backup.log 2>&1

Restore the gateway state

Steps

1. In the install directory, run the restore script:

   bash scripts/restore.sh /backup/rst-copilot/gateway-state-<time>.tar.gz

   The script stops the containers (without deleting volumes), restores the machine-id-<time> taken at the same time, empties and refills the volume, and starts the containers. You can also pass the machine-id file as the second argument.

2. Open License and check that the license status is valid.

The machine-id must be the one in place when the license was activated; otherwise the license reports that it is bound to another machine. When restoring onto a different host, the license may need to be activated again. For an online-activated license, first select Deactivate this license under Deactivate on the old host.

Retention

These data in the gateway_state volume are cleaned up automatically per the table. To change a retention period, set the matching setting in .env and recreate the gateway container.