Upgrade and backup¶

Availability

Deployment: Self-managed deployments only.

On a self-managed deployment, you run upgrades and backups. This page covers both the Compose bundle and the Helm chart.

Release versions¶

Each release has a Release version in the form YYYY.MM.DD.N, for example 2026.10.08.8. You find it in the Release bundle's VERSION file. Release numbers aren't consecutive. See Release bundle.

Contact Actian to confirm which version to install and whether you can upgrade directly from your current version.

Before you upgrade¶

Verify the new Release bundle.
Take a backup. There is no downgrade: if the upgrade fails, you restore this backup. See Back up and restore the Compose bundle or Back up a Helm installation.
Plan for a short interruption. The containers or pods restart with the new images.

Upgrade the Compose bundle¶

Running the new bundle's installer over your existing installation is the upgrade.

Back up the installation.
From the new, extracted Release bundle, run the installer with the same target directory as your existing installation:
```
./install.sh /path/to/ai-analyst
```
The installer:
- Verifies the bundle and loads every image into Docker.
- Detects the upgrade because .env already exists in the target directory.
- Copies the new bundle's Compose files over the old ones.
- Keeps .env, ./licence and ./certs.
- In .env, rewrites only the *_IMAGE lines and AI_ANALYST_VERSION. Your other values and comments stay as they are.
Start the stack:
```
cd /path/to/ai-analyst
docker compose up -d --wait
```
If you use the compose.customer-network.yml override, pass both files as you normally do.

On every start, the one-shot migrate service applies the new database schema. The server starts only after migrate finishes successfully.

Local edits to bundle files are overwritten

The installer replaces every file that ships in the bundle, including docker-compose.yml, the proxy configuration and the Keycloak realm template. Keep your settings in .env, ./licence and ./certs, and reapply any other local edit after each upgrade.

Keycloak during an upgrade¶

Keycloak keeps its realm across upgrades. It imports the realm only when the realm doesn't exist yet, so changes you made in the Keycloak admin console survive. For the same reason, changes to the realm template in a new release aren't applied to your existing realm.

One case needs a manual step: a realm imported before the bundle shipped AI Analyst's sign-in pages keeps Keycloak's own. To switch it, see Sign-in page language and theme.

Upgrade the Helm release¶

Back up the installation.
Push the new bundle's images to your registry. See Install on Kubernetes with Helm.
In your values file, set the image tags to the new bundle's VERSION.

Run helm upgrade with the new bundle's chart:

helm upgrade ai-analyst helm/ai-analyst-*.tgz -n ai-analyst -f values-airgap.yaml --wait --timeout 15m

Use your own release name, namespace and values file.

The upgrade runs in this order:

Database bootstrap Job (only with dbBootstrap.enabled): creates the vector and pg_trgm extensions if they're missing.
Migration Job: applies the new database schema.
Rolling update: the Deployments roll to the new images.

The server, web, Keycloak and JDBC bridge Deployments replace pods one at a time, without adding an extra pod first. A Deployment with a single replica, which is the default in the Air-gapped example values, is briefly unavailable while its pod restarts. The chart's optional embeddings Deployments start a new pod before they stop the old one.

With the chart-managed Keycloak (keycloak.enabled: true), the realm is kept across upgrades, as in the Compose bundle.

Roll back¶

There is no downgrade: database migrations only move forward. To roll back, restore the backup you took before the upgrade, and run the previous version against it.

Compose bundleHelm chart

Run the previous bundle's install.sh over the installation, so that the images and Compose files match the backup.
Restore the backup into the installation, which ends with docker compose up -d --wait. See Restore.

Restore your pre-upgrade Postgres backup (and object storage, if needed) with your usual tooling.
Run helm upgrade with the previous bundle's chart and image tag.

Don't rely on helm rollback on its own: it doesn't reverse the database migrations.

Back up and restore the Compose bundle¶

What to back up¶

All state lives in four named Docker volumes:

Volume	Holds
`ai-analyst_postgres_data`	The product database and Keycloak's database (users, organizations, sessions and realm settings).
`ai-analyst_storage_data`	Uploaded files, converted Parquet files and attachments.
`ai-analyst_proxy_data`	The proxy's internal certificate authority (CA) and certificates.
`ai-analyst_proxy_config`	The proxy's autosaved configuration. You don't need to back it up.

Keycloak keeps no other state on disk: backing up Postgres backs up Keycloak.

Keep these with every backup:

.env. It holds WAREHOUSE_CREDENTIAL_ENCRYPTION_KEY. If you lose this key, you lose every stored warehouse credential, every API key for an LLM or Embedding endpoint that an organization added under Settings → Inference, and the catalog connection secrets. See Credential encryption key.
./licence, with your Licence.
./certs, if you use your own TLS certificate.

If the proxy volume is lost

The proxy creates a new internal CA. If members trusted the old CA, they must trust the new one. This doesn't apply when you use your own certificate.

Back up while the stack runs¶

Run these from the installation directory:

docker compose exec -T postgres pg_dumpall -U aianalyst --clean --if-exists > ai-analyst-$(date +%F).sql
docker run --rm -v ai-analyst_storage_data:/data -v "$PWD":/backup alpine \
  tar czf /backup/storage-$(date +%F).tgz -C /data .

Replace aianalyst if you changed POSTGRES_USER in .env.
The dump contains Keycloak users and sessions and encrypted credentials, and .env holds all your secrets. Store backups with restricted access, and make sure everyone who can read a backup is allowed to read .env as well.
The two commands run one after the other, so the database dump and the storage archive aren't captured at exactly the same moment. For a point-in-time copy, use the offline method.

Back up offline¶

Stop the stack, snapshot the volumes with your usual tooling, then start it again:

docker compose stop
# snapshot the ai-analyst_* volumes
docker compose up -d --wait

Restore¶

To restore an online backup into an empty installation:

docker compose down -v
docker compose up -d --wait postgres
docker compose exec -T postgres psql -q -U aianalyst -d postgres < ai-analyst-<date>.sql
docker run --rm -v ai-analyst_storage_data:/data -v "$PWD":/backup alpine \
  tar xzf /backup/storage-<date>.tgz -C /data
docker compose up -d --wait

Warning

docker compose down -v deletes the installation's volumes, including the current database and uploaded files. Run it only when you mean to replace them with the backup.

psql reports that the current user can't be dropped and already exists. Both messages are expected.

Make sure .env and ./licence match the backup, in particular WAREHOUSE_CREDENTIAL_ENCRYPTION_KEY.

Back up a Helm installation¶

With the Helm chart, the data lives in services you run, so back them up with your existing tooling:

What	Where it lives
Product database	The `app` database on your Postgres.
Keycloak data	The `keycloak` database on your Postgres, when the chart runs Keycloak (`keycloak.enabled: true`). If you run your own Keycloak, back it up separately.
Uploaded files, Parquet files and attachments	Your S3-compatible bucket, named in `S3_BUCKET`.
Encryption key	`WAREHOUSE_CREDENTIAL_ENCRYPTION_KEY` in the Secret named in `server.existingSecret` (`ai-analyst-secrets` in the example values). If you lose it, you lose every stored warehouse credential, every API key for an LLM or Embedding endpoint that an organization added under Settings → Inference, and the catalog connection secrets. See Credential encryption key.
Licence	The Secret named in `server.licence.existingSecret` (`ai-analyst-licence` in the example values), which holds `licence.json` and `licence-public.pem`.

Keep a copy of the whole server Secret with the backup, and of your other Secrets (the web configuration Secret, and the Keycloak Secret named in keycloak.existingSecret with the chart-managed Keycloak) and your values file. Backups contain secrets, so store them with restricted access.

Change configuration after install¶

Compose bundleHelm chart

Edit .env.
Run docker compose up -d --wait. Compose recreates the containers whose settings changed.

The bundle passes to the containers only the settings that its Compose file lists. See the Configuration reference for what each setting does.

Keep your settings in .env. Edits to other files that ship in the bundle, such as docker-compose.yml, are overwritten at the next upgrade. See Upgrade the Compose bundle.

A setting in a Secret (the server Secret, the web configuration Secret or the Keycloak Secret): edit the Secret, then restart the Deployments that read it, for example:
```
kubectl -n ai-analyst rollout restart deployment/ai-analyst-server-server
```
These names assume the release name ai-analyst and the Secret names from the install guide. A server Deployment is named <release>-server-<entry name>.

Pods read their Secrets when they start, so a changed Secret has no effect until you restart them. The server Deployments read the Secret named in server.existingSecret (ai-analyst-secrets in the example values), the web Deployment reads its own configuration Secret (ai-analyst-web-config in the example), and the chart-managed Keycloak reads the Secret named in keycloak.existingSecret (ai-analyst-keycloak in the example).
A chart value (network posture, replicas, resources, enabled components, image tags or extraCaCerts): edit your values file and run helm upgrade again.

Some settings can't usefully change after the first start:

Operator bootstrap settings (BOOTSTRAP_*) apply only on the first boot. Manage the organization and its members in Settings instead. See Identity and first sign-in.
WAREHOUSE_CREDENTIAL_ENCRYPTION_KEY encrypts stored warehouse credentials, the API keys of LLM and Embedding endpoints that organizations add under Settings → Inference, and catalog connection secrets. Rotating this key isn't supported. A different key can't read what the old one encrypted. See Credential encryption key.

See the Configuration reference for every setting.

Troubleshooting¶

The server doesn't start after a Compose upgrade. Check the migration first: docker compose logs migrate. The server waits for migrate to finish successfully. Then check docker compose logs server; when the server refuses to start, it names the setting it objects to.

Helm upgrade times out. Check the migration Job's logs first: the hook Jobs run before the Deployments roll. Then check the new pods' events for image-pull errors, insufficient resources or failing probes. server.healthProbePath must match your API path prefix.

Server pods fail their startup probe during a first install. The chart's hook Jobs run only on helm upgrade, so on a first install the server pods fail their startup probe and restart until the second command, helm upgrade, has run them. See Install on Kubernetes with Helm.

Sign-in looks like Keycloak's default pages after an upgrade. Your realm predates AI Analyst's sign-in pages. See Sign-in page language and theme.

Stored connections or Inference endpoints stop working after a restore. The restored database was encrypted with a different WAREHOUSE_CREDENTIAL_ENCRYPTION_KEY. Restore the .env (or Secret) that belongs to the backup.