---
description: Upgrade a self-managed Actian AI Analyst deployment, back it up and restore it, roll back after a failed upgrade, and change its configuration, for both the Compose bundle and the Helm chart.
---

# Upgrade and backup

!!! info "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](release-bundle.md).

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

## Before you upgrade

1. [Verify the new Release bundle](release-bundle.md).
2. Take a backup. There is no downgrade: if the upgrade fails, you restore this backup. See [Back up and restore the Compose bundle](#back-up-and-restore-the-compose-bundle) or [Back up a Helm installation](#back-up-a-helm-installation).
3. 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.

1. Back up the installation.
2. From the new, extracted Release bundle, run the installer with the same target directory as your existing installation:

    ```sh
    ./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.

3. Start the stack:

    ```sh
    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.

!!! warning "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](identity-and-first-sign-in.md#sign-in-page-language-and-theme).

## Upgrade the Helm release

1. Back up the installation.
2. Push the new bundle's images to your registry. See [Install on Kubernetes with Helm](install-kubernetes-helm.md).
3. In your values file, set the image tags to the new bundle's `VERSION`.
4. Run `helm upgrade` with the new bundle's chart:

    ```sh
    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:

1. **Database bootstrap Job** (only with `dbBootstrap.enabled`): creates the `vector` and `pg_trgm` extensions if they're missing.
2. **Migration Job**: applies the new database schema.
3. **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 bundle"

    1. Run the previous bundle's `install.sh` over the installation, so that the images and Compose files match the backup.
    2. Restore the backup into the installation, which ends with `docker compose up -d --wait`. See [Restore](#restore).

=== "Helm chart"

    1. Restore your pre-upgrade Postgres backup (and object storage, if needed) with your usual tooling.
    2. 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](configuration-reference.md#credential-encryption-key).
- `./licence`, with your [Licence](licence.md).
- `./certs`, if you use your own TLS certificate.

!!! note "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:

```sh
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:

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

### Restore

To restore an online backup into an empty installation:

```sh
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](configuration-reference.md#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 bundle"

    1. Edit `.env`.
    2. 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](configuration-reference.md) 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](#upgrade-the-compose-bundle).

=== "Helm chart"

    - **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:

        ```sh
        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](identity-and-first-sign-in.md#operator-bootstrap-the-first-organization).
- **`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](configuration-reference.md#credential-encryption-key).

See the [Configuration reference](configuration-reference.md) 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](install-kubernetes-helm.md).

**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](identity-and-first-sign-in.md#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.