Upgrade, rollback and backup

Three ways to upgrade (re-run deploy.sh in place, online update, manual tag switch), health-gated rollback, the four things to back up, and the restore drill.

Upgrading

Option 1: new archive, deploy.sh in the same directory

Unpack the new archive into the same directory (scripts and compose files are replaced; .env and state/ are not) and run again:

rm -f /opt/rst-copilot/RST-Elastic-AI-Copilot-images-*.tar   # remove the old image bundle first, see below
tar xzf RST-Elastic-AI-Copilot-<new>.tar.gz --strip-components=1 -C /opt/rst-copilot
cd /opt/rst-copilot && ./deploy.sh      # Y to "keep the existing .env and start?", Y to "upgrade to <new>?"

It docker loads the new image, switches GATEWAY_IMAGE_TAG, restarts with --force-recreate and waits for healthy. Afterwards confirm docker inspect rst-elastic-ai-copilot-gateway --format '{{.Config.Image}}' shows the new version.

deploy.sh up to 1.1.21 loads only the first RST-Elastic-AI-Copilot-images-*.tar by file name. With the old bundle still in the directory it reloads the old image, leaves GATEWAY_IMAGE_TAG unchanged and still prints 部署完成. From 1.1.22 it loads every bundle and switches to the newest.

Option 2: online update

A gateway with an online licence learns about new versions over the heartbeat. Under Settings → Version and update click "Download and stage"; the gateway verifies the signature and stores the image under ./release/staging. Then on the host:

./deploy/rst-update.sh              # load staged image → switch GATEWAY_IMAGE_TAG → health probe
./deploy/rst-update.sh --rollback   # back to the previous version

Three consecutive 200s on /healthz count as success; otherwise it rolls back automatically.

Option 3: by hand

docker load < RST-Elastic-AI-Copilot-images-<new>.tar
sed -i 's/^GATEWAY_IMAGE_TAG=.*/GATEWAY_IMAGE_TAG=<new>/' .env
docker cp rst-elastic-ai-copilot-gateway:/app/state/server_guid state/server_guid 2>/dev/null || true   # when coming from 1.1.20 or earlier
docker compose -f docker-compose.prod.yml up -d

Rollback

Restart on the previous tag:

sed -i 's/^GATEWAY_IMAGE_TAG=.*/GATEWAY_IMAGE_TAG=<previous>/' .env
docker compose -f docker-compose.prod.yml up -d

Licence state lives in state/ and the gateway_state volume, not in the image; rollback keeps it.

Whichever route: never docker compose down -v, never regenerate state/machine-id / state/server_guid. The volume and those two files together are the licence's host identity.

Version-specific notes (offline licence re-issue, heartbeat fix, server_guid migration) are under Activation → Upgrade notes.

What to back up

Where data lives

Data	Where	How
Host identity (machine-id + server_guid)	`./state/`	The whole directory
Gateway config, licence activation, quota, providers, channel secrets	`gateway_state` volume (`/app/state`)	`scripts/backup.sh`
Accounts / roles	`userdb_data` volume (Postgres)	`pg_dump`
Audit, knowledge base, conversations, reports, records, alerts, ledger	`.rst_copilot_*` in your ES	Add to your ES snapshot policy

Gateway state

bash scripts/backup.sh /backup/rst-copilot     # gateway-state-<timestamp>.tar.gz, keeps 30 days

Suggested cron, daily at 02:00:

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

That archive is effectively plaintext: it holds the encrypted ES password / SMTP password / webhook secrets together with the .rst_secret_key that decrypts them. chmod 700 the backup directory and encrypt again before moving it off the host. Restores must include .rst_secret_key (or the same RST_SECRET_KEY environment variable), or those secrets show as "not set" in the UI.

Restore:

bash scripts/restore.sh /backup/rst-copilot/gateway-state-XXXX.tar.gz
docker compose -f docker-compose.prod.yml restart gateway

Account table

docker exec rst-elastic-ai-copilot-userdb pg_dump -U rst rst_users > /backup/rst-copilot/users-$(date +%F).sql
# restore
docker exec -i rst-elastic-ai-copilot-userdb psql -U rst rst_users < users-XXXX.sql

Losing this volume does not brick the deployment: the gateway recreates the table and re-seeds the first administrator from .env, but every other account is gone.

ES indices

Use native ES snapshots; add .rst_copilot_* to your existing snapshot's index list:

PUT /_snapshot/<repo>/snap-20260915?wait_for_completion=true
{ "indices": ".rst_copilot_*", "include_global_state": false }

Keep audit logs at least 180 days.

Restore drill

Rehearse at least once before go-live: restore.sh + an ES _restore on a test host, then confirm the gateway comes up with the licence valid and audit / knowledge-base data present. Restoring onto a different host means a new fingerprint and a re-activation; deactivate the online licence on the old host first.

Upgrade, rollback and backup

On this page