---
description: What the Actian AI Analyst Release bundle contains, how to verify its signatures and checksums offline, and how Connected installs can pull images by digest instead.
---

# Release bundle and verification

!!! info "Availability"
    - **Deployment:** Self-managed deployments only.

The Release bundle is the versioned, offline-installable package Actian delivers for a self-managed deployment. It contains every container image as a tarball, the Helm chart, the Compose bundle, a software bill of materials (SBOM) for each image, and signatures you can check without network access.

The bundle is built for `linux/amd64` only. It contains no model runtime or model weights: chat needs an OpenAI-compatible API that you run. See [Configure inference](configure-inference.md).

## What you receive

Actian delivers each release as five files. `<VERSION>` is the Release version, in the form `YYYY.MM.DD.N`.

| File | What it is |
|---|---|
| `ai-analyst-<VERSION>.tar.gz` | The bundle archive (about 1 GB). |
| `ai-analyst-<VERSION>.tar.gz.sig` | The archive's detached signature. |
| `ai-analyst-<VERSION>.tar.gz.sha256` | The archive's SHA-256 checksum. |
| `ai-analyst-<VERSION>.cosign.pub` | The public half of the release signing key. |
| `ai-analyst-<VERSION>.manifest.json` | A copy of the bundle's `manifest.json`, so you can review the contents before you extract the archive. |

`manifest.json` records the version and source commit, every image (its reference, source, registry digest, tarball, SHA-256 and SBOM path), the Helm chart file, version and SHA-256, and the SHA-256 fingerprint of the signing key.

## Bundle contents

Extracting the archive creates an `ai-analyst-<VERSION>/` directory:

| Path | Contents |
|---|---|
| `VERSION` | The Release version. |
| `manifest.json` | The manifest described above. |
| `images.txt` | One line per image: `name image tarball`. `install.sh` loads the images listed here. |
| `images/*.tar` | `docker save` tarballs for `linux/amd64`: `server.tar`, `web.tar`, `jdbc-bridge.tar`, `postgres.tar` (pgvector), `keycloak.tar` and `caddy.tar`. |
| `sbom/*.cdx.json` | One CycloneDX SBOM per image, for example `sbom/server.cdx.json`. |
| `helm/` | The Helm chart (`ai-analyst-<chart version>.tgz`), `values-airgap.example.yaml`, and the Air-gapped Helm guide `helm-airgap.md`. |
| `compose/` | The Compose bundle: `docker-compose.yml`, `compose.customer-network.yml`, `.env.example`, its README, the Keycloak realm template and login theme, the Postgres script that creates Keycloak's database, the Caddy proxy configuration, and empty `certs/` and `licence/` directories. |
| `*.sig` | Signatures beside each image tarball, each SBOM, the Helm chart, `manifest.json` and `SHA256SUMS`. |
| `SHA256SUMS` | The checksum of every other file in the bundle. |
| `cosign.pub` | The release signing public key. |
| `README.md`, `verify.sh`, `install.sh` | Bundle instructions, the verification script and the Compose installer. |

Files without their own signature, such as `VERSION`, the scripts and the `compose/` files, are covered by `SHA256SUMS`, whose signature vouches for the whole tree.

The third-party images are pinned by digest: `pgvector/pgvector:pg16`, `quay.io/keycloak/keycloak:26.5` and `caddy:2.10-alpine`.

## Verify the archive before you carry it across the air gap

Run these commands on a machine with `openssl`, in the directory that holds the five files:

```sh
sha256sum -c ai-analyst-<VERSION>.tar.gz.sha256
base64 -d ai-analyst-<VERSION>.tar.gz.sig > archive.sig.der
openssl dgst -sha256 -verify ai-analyst-<VERSION>.cosign.pub \
  -signature archive.sig.der ai-analyst-<VERSION>.tar.gz
```

`openssl` prints `Verified OK` when the signature matches.

## Verify the extracted bundle

1. Extract the archive and change into the bundle directory:

    ```sh
    tar -xzf ai-analyst-<VERSION>.tar.gz
    cd ai-analyst-<VERSION>
    ```

2. Run the verification script:

    ```sh
    ./verify.sh
    ```

    `verify.sh` checks the signature on `SHA256SUMS`, then every file's checksum, then each signed file's own signature. It stops with a non-zero exit code at the first mismatch. On success it prints `Release bundle verified.`

3. Compare the fingerprint. `verify.sh` prints a line like this:

    ```text
    Public key sha256: <fingerprint>
    ```

    Because `cosign.pub` ships inside the bundle it vouches for, a passing run proves only that the bundle matches that key. Before you trust the result, compare the fingerprint with the one Actian gives you for the release through a separate channel. You can also compute it yourself with `sha256sum ai-analyst-<VERSION>.cosign.pub`.

!!! warning
    Don't use the `publicKeySha256` value inside `manifest.json` as your independent check. The same key signs the manifest.

`verify.sh` needs `bash`, GNU coreutils (`sha256sum`, `base64`) and `openssl`. With `openssl` it makes no network call: the signatures are cosign key-based signatures (ECDSA P-256 over SHA-256), which `openssl` verifies directly.

### Use cosign instead of openssl

By default, `verify.sh` uses `openssl` when it's on the `PATH` and falls back to cosign only when `openssl` is missing. To choose cosign (v2) explicitly:

```sh
VERIFY_WITH=cosign ./verify.sh
```

cosign may try to reach Sigstore's update mirror and continues when it can't. The result doesn't depend on that call, but if you need a strictly offline check, use `openssl`.

## SBOMs

Each image has a CycloneDX JSON SBOM in `sbom/`, generated from the image tarball in the bundle and signed with the release key. Use the SBOMs as an inventory for your own vulnerability scanning and software review.

## Install from the bundle

- **One host:** `./install.sh <target directory>` verifies the bundle, loads every image into Docker, copies the Compose files into the target and pins every image in `.env`. See [Install with Docker Compose](install-docker-compose.md).
- **Kubernetes:** push the images to your own registry and install the chart. See [Install on Kubernetes with Helm](install-kubernetes-helm.md).

!!! note "Digests in your own registry"
    When you push the images to a private registry, the registry may report a digest that differs from `manifest.json`, because pushing re-encodes the image manifest. The bundle's signatures cover the tarballs you pushed from. To pin by digest, use the digest your registry reports.

## Connected installs: pull images from a registry

A Connected self-managed deployment can pull images instead of loading the tarballs:

- The product images (`server`, `web` and `jdbc-bridge`) come from Actian's customer registry. Contact Actian for the registry address and access.
- The third-party images (Postgres with pgvector, Keycloak and Caddy) come from their upstream registries.

Always pull by digest from the release's `manifest.json`, never by a moving tag. For product images, use `images[].digest`. For third-party images, use `images[].source`, which is a `tag@digest` reference.

```sh
REGISTRY=<ACTIAN_REGISTRY>
docker pull "$REGISTRY/server@sha256:<digest>"
docker pull "$REGISTRY/web@sha256:<digest>"
docker pull "$REGISTRY/jdbc-bridge@sha256:<digest>"
```

### Verify pulled product images

Actian's build pipeline signs the product images with cosign keyless signing. Actian supplies the signer identity and issuer values with the registry address and access. Verify a pulled image with:

```sh
cosign verify \
  --certificate-identity-regexp '<SIGNER_IDENTITY_REGEXP>' \
  --certificate-oidc-issuer '<SIGNER_OIDC_ISSUER>' \
  "$REGISTRY/server@sha256:<digest>"
```

The identity value is what the signature certificate must contain. Keyless verification needs network access to Sigstore. The third-party images are not signed by Actian.

### Point your install at the pulled images

=== "Compose bundle"

    Set these variables in `.env` to the `…@sha256:<digest>` references: `SERVER_IMAGE`, `WEB_IMAGE`, `JDBC_BRIDGE_IMAGE`, `POSTGRES_IMAGE`, `KEYCLOAK_IMAGE` and `CADDY_IMAGE`.

=== "Helm chart"

    For `server.image`, `web.image` and `jdbcBridge.image`, set `repository` to the registry path and `tag` to `<VERSION>@sha256:<digest>`. Set `keycloak.image` the same way, using its upstream tag (for example `26.5@sha256:<digest>`). Set `dbBootstrap.image` to the full Postgres reference.

    ```yaml
    server:
      image:
        repository: <registry>/server
        tag: "<VERSION>@sha256:<digest>"
    ```

## Troubleshooting

**`verify.sh` reports `FAIL: bad signature` or a checksum mismatch.**
Don't install the bundle. Download or copy the files again and re-run the checks. If the failure persists, contact Actian.

**`verify.sh needs openssl or cosign on PATH`.**
Install `openssl` (recommended for offline checks) or cosign v2.

**`sha256sum: command not found`.**
`verify.sh` needs GNU coreutils. Run it on a Linux host, or install coreutils.