Release package and offline installation

What this page covers

The release package is the primary installation path on Linux. Release files include the package, SHA-256 list, Sigstore verification data, image manifest, and image bundles for each architecture. Verify the files before installing.

How to set it up

Release download guide

From 1.14.0, Linux hosts can use the fixed-name release guide. It downloads the latest package and SHA256SUMS, checks the package SHA-256 before unpacking to /opt/custodexa, and opens the custodexa.sh menu:

set -o pipefail
curl -fsSL https://github.com/custodexa/custodexa/releases/latest/download/get-custodexa.sh | sudo bash

To pin a version and folder:

set -o pipefail
curl -fsSL https://github.com/custodexa/custodexa/releases/latest/download/get-custodexa.sh | sudo bash -s -- --version 1.14.0 --dir /srv/custodexa

To inspect the guide first:

curl -fsSLO https://github.com/custodexa/custodexa/releases/latest/download/get-custodexa.sh
sudo bash get-custodexa.sh

In Bash or Zsh, set -o pipefail makes a failed guide download return a nonzero status for the whole pipeline. For the download-then-run form, run the second command only after the download succeeds. Setting CX_GET_RELEASE_BASE to another release endpoint trusts that source for both the package and SHA256SUMS; matching hashes alone do not verify the publisher.

The guide does not verify the package signature; follow the manual check below. custodexa.sh handles image signatures. An existing deployment is handed to its management script without overwriting it.

Manual download, signature verification, and installation

Download custodexa-1.14.0.tar.gz, SHA256SUMS, and SHA256SUMS.sigstore.json from the 1.14.0 release. In their directory, run:

sha256sum --ignore-missing -c SHA256SUMS
cosign verify-blob --bundle SHA256SUMS.sigstore.json \
  --certificate-identity "https://github.com/custodexa/custodexa/.github/workflows/release-images.yml@refs/tags/v1.14.0" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
  SHA256SUMS
sudo tar -xzf custodexa-1.14.0.tar.gz -C /opt
sudo /opt/custodexa/custodexa.sh install

The installer checks the host and Docker environment, creates .env, obtains and verifies images, starts services, and waits for health checks. It looks for images locally, in an offline bundle, on GHCR, on Docker Hub, then builds from source. Persistent data lives under DATA_PATH. The initial password is used for first login and then changed in the interface.

Use custodexa.sh for installation. install and the menu offer Auto or Build from the source in the package; the command accepts --images-from auto|source and defaults to auto. Auto checks images on this host, an offline bundle, GHCR, Docker Hub, then builds locally. Source verifies the package source before building backend and frontend. Upstream images, base images and build dependencies still have to be obtained; this is not a fully offline choice. --images <bundle> can only be combined with Auto. Long downloads and checks show [ .. ] before they run, then [ OK ], [WARN] or [FAIL] with the result.

sudo /opt/custodexa/custodexa.sh install --images-from source

Offline images

Obtain the image bundle for the host architecture, such as custodexa-images-1.14.0-amd64.tar, and place the matching version’s SHA256SUMS in the same directory. With both files in /srv/custodexa-1.14.0/, load the bundle before installation:

sudo /opt/custodexa/custodexa.sh load /srv/custodexa-1.14.0/custodexa-images-1.14.0-amd64.tar
sudo /opt/custodexa/custodexa.sh install

Run sudo /opt/custodexa/custodexa.sh without arguments for the menu covering install, load, status, upgrade, and backup. --help lists commands. --lang zh-TW, --lang en, or --lang ja selects the menu language. Check services and version with sudo /opt/custodexa/custodexa.sh status.

What auditors can see

After deployment, logins and managed sessions enter the audit trail. Command records are searchable, while the recording is the source of truth for text sessions; input without echo leaves no command-text record. The query console’s structured statement record is the source of truth for that query.