Installing from the archive

The gateway is published on GitHub Releases as the archive RST-AI-Copilot-for-Zabbix-<version>.tar.gz, with a .sha256 file of the same name for verification and release-manifest.token, the release manifest signed by Reallysec. The archive carries the images and deployment files, and its deploy.sh does the installation: it loads the images, collects the configuration, writes .env and starts the containers. install.sh combines download, signature check, unpacking and deploy.sh into one command.

Archive contents

RST-AI-Copilot-for-Zabbix-<version>/
├── RST-AI-Copilot-for-Zabbix-images-<version>.tar   # gateway and Caddy images
├── deploy.sh                                    # interactive installer
├── docker-compose.prod.yml                      # standard deployment
├── docker-compose.sso.yml                       # SSO
├── Caddyfile, Caddyfile.sso
├── .env.example                                 # settings, with notes
├── deploy/rst-update.sh                         # online update installer
├── keycloak/                                    # Keycloak config for the SSO demo
├── scripts/backup.sh, scripts/restore.sh
├── docs/                                        # INSTALL.md, LICENSING.md, BACKUP.md, SSO.md, EULA.md and more
└── THIRD-PARTY-NOTICES.md, CHANGELOG.md

Install with one command

Prerequisites

• Docker Engine 24 or later and Docker Compose v2 are installed, along with curl, tar, sha256sum, base64 and openssl.
• The host can reach github.com.
• You run the command as root from an interactive terminal, because deploy.sh reads input.

Steps

1. Run the installer:

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

   Every edition uses the same archive: without a license it runs as Community, and activating a license under Settings > License unlocks that edition in place, with no reinstall.

2. Answer the deploy.sh prompts. See deploy.sh prompts below.

The script first downloads the signed release manifest release-manifest.token and verifies it with the embedded Reallysec public key. It then downloads the archive and continues only if its SHA-256 matches the manifest; otherwise it deletes the download and exits without installing anything. If the newest release has just been published and its manifest is not uploaded yet, the script skips it and installs the newest signed release.

After the checks pass, the archive is unpacked into /opt/rst-ai-copilot-for-zabbix and deploy.sh runs there. When you run it again on the same host, .env and state/ in that directory are kept, and the license's host fingerprint does not change. The same command therefore upgrades an install.

Options go after bash -s --:

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

If a GitHub download stays below 10 KB/s for 30 seconds, the script treats it as failed and exits. On a slow network, download with --download-only on another machine and copy the archive over, as described below.

Install on an air-gapped host

Steps

1. On a Linux machine that can reach GitHub, download and verify the archive. This step needs neither root nor Docker:

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

2. Copy RST-AI-Copilot-for-Zabbix-<version>.tar.gz from the current directory to the air-gapped host.

3. On the air-gapped host, unpack it and run deploy.sh:

   tar xzf RST-AI-Copilot-for-Zabbix-<version>.tar.gz
   cd RST-AI-Copilot-for-Zabbix-<version>
   sudo ./deploy.sh

A license on an air-gapped host needs offline activation (Enterprise). See License.

Install the archive by hand

Steps

1. Download RST-AI-Copilot-for-Zabbix-<version>.tar.gz and its .sha256 file from GitHub Releases. Every edition uses the same archive; the activated license decides which features are on.

2. Verify and unpack it:

   sha256sum -c RST-AI-Copilot-for-Zabbix-<version>.tar.gz.sha256
   tar xzf RST-AI-Copilot-for-Zabbix-<version>.tar.gz
   cd RST-AI-Copilot-for-Zabbix-<version>

3. Run sudo ./deploy.sh and answer the prompts.

The .sha256 file comes from the same place as the archive, so it only catches transfer damage. To confirm the archive was really published by Reallysec, use install.sh, which checks the signed manifest.

deploy.sh prompts

The script runs in seven steps: preflight, image load, check for an existing .env, deployment form, configuration, write .env, start.

• The preflight checks Docker, Docker Compose v2 and the deployment files, and generates state/machine-id, the license's hardware fingerprint. If the file exists it is reused.
• If .env already exists, the script asks whether to keep it and start; the default is no. Enter y when upgrading. If you answer no, the old file is backed up as .env.<time>.bak and you fill in the values again.
• The archive only carries the standard form, which connects to your existing Zabbix, so there is nothing to choose in that step.

The script generates RST_GATEWAY_SHARED_SECRET, RST_ADMIN_TOKEN and the administrator password hash RST_ADMIN_PASSWORD_HASH (computed with the gateway image), and after you confirm writes them to .env with mode 600. After starting, it waits up to 90 seconds for every container to become healthy, then prints the URL https://<hostname>/v2/, the sign-in account admin and RST_ADMIN_TOKEN. RST_ADMIN_TOKEN is the operations API token that scripts send in the X-RST-Admin-Token header; keep it like a password.

deploy.sh does not configure SSO. See SSO.

Verify the installation

Steps

1. Check health and readiness:

   curl -k https://<hostname>/healthz     # {"status":"ok"}
   curl -k https://<hostname>/readyz
   docker compose -f docker-compose.prod.yml ps

2. Open https://<hostname>/v2/, check that you land on the sign-in page, and sign in as admin with the password you set during installation.

A ready gateway returns {"status":"ready","zabbix":"ok","zabbix_major":"<major version>"}. On a 503, the zabbix field holds the reason: a connection or authentication error, or a Zabbix version older than 6.0 (code is zabbix_version_unsupported). readyz calls Zabbix on every request, so it works as a monitoring probe.

The default certificate comes from Caddy's internal CA, and browsers warn on first visit. For production, replace tls internal in Caddyfile with your own certificate.

Install without deploy.sh

Steps

1. Load the images and prepare .env:

   docker load -i RST-AI-Copilot-for-Zabbix-images-<version>.tar
   cp .env.example .env

2. In .env, set LLM_API_KEY, LLM_BASE_URL, LLM_MODEL, ZABBIX_URL, ZABBIX_TOKEN and CADDY_SITE_ADDRESS, plus RST_GATEWAY_SHARED_SECRET and RST_ADMIN_TOKEN generated with openssl rand -hex 32.

3. Generate the administrator password hash and write it to RST_ADMIN_PASSWORD_HASH in .env, doubling every $ as $$:

   docker run --rm rst-ai-copilot-for-zabbix-gateway:<version> python -m backend.session_auth '<password>'
   # pbkdf2_sha256$600000$...  becomes  pbkdf2_sha256$$600000$$...

   Without it, the factory credentials admin / Admin@123 apply. They only work from the gateway host itself; a remote browser sign-in returns 403.

4. Generate the host fingerprint file, once:

   mkdir -p state
   openssl rand -hex 16 > state/machine-id

5. Run docker compose -f docker-compose.prod.yml up -d. The archive has no Dockerfile, so do not add --build.

Next steps

1. To use the paid features, activate a license on the License page.
2. Configure the host group allowlist, field masking and audit in Settings.
3. Include ./state/machine-id and the gateway_state volume in backups. See Upgrade, rollback and backup.