Skip to content

Standalone Bundle Install (Offline, CLI-Managed)

This guide covers installing the Connector from a signed release bundle using the a10e CLI, without cloning this repository or building images yourself. It’s the recommended path when the target host cannot reach Alien Giraffe’s release bucket directly, or when you want to inspect and verify every file before it touches a server.

The CLI normally installs the Connector in one command (sudo a10e install): it reads the signed release manifest, downloads the matching bundle, verifies it, extracts it to /opt/a10e, loads the Docker images, registers a systemd service, and starts everything. This guide walks through the same result step by step:

  1. Download the release files (the a10e CLI, manifest.json, its signature, and the Connector bundle) from the release bucket on a machine that has access, and verify the signatures and checksums yourself.
  2. Copy the files to the target host and install the Connector from them.

For the fully-manual alternative (no CLI at install time — troubleshooting or hosts where the CLI can’t run), see Manual Bundle Install. For the release bucket layout, host prerequisites, how the bundle actually runs, and a quick-reference table of the resulting file layout, see Bundle Install Reference — this page assumes you’ve read it.

For Red Hat Enterprise Linux (RHEL), select the connector-data-rhel release channel. Install the a10e CLI for your host’s architecture using the download and verification instructions, and ensure the target-host prerequisites are met.

On a host with access to the release bucket and the supplied read credentials available to the CLI, run as root:

a10e install --channel connector-data-rhel

If you’re using an account with sudo, run sudo a10e install --channel connector-data-rhel with the bucket credentials available to that invocation.

If the first run asks for JWT_SECRET, fill in the shared environment, then rerun the same RHEL-channel command. Once installation completes, verify everything is running.

For an offline RHEL install, follow the walkthrough below with CHANNEL=connector-data-rhel when downloading the release files, and replace --channel stable in every install command (including the rerun after setting JWT_SECRET) with --channel connector-data-rhel:

sudo a10e install --source /opt/a10e-dist --channel connector-data-rhel

The channel selects the RHEL release bundle; the CLI’s container-runtime prerequisites still apply. For a Podman-only host, follow Manual Bundle Install → Using Podman instead of Docker, selecting connector-data-rhel when downloading the bundle.

If you just want a running Connector with the fewest possible steps, sync the whole release bucket, copy it to the target VM, and install from that local directory:

# 1. On a machine with bucket access: sync the whole release bucket locally
export AWS_REGION=us-west-1
export AWS_ACCESS_KEY_ID=...
export AWS_SECRET_ACCESS_KEY=...
aws s3 sync s3://a10e-releases ./a10e-dist
# 2. Copy everything to the target VM
scp -r ./a10e-dist user@target-vm:~/a10e-dist
# 3. SSH into the VM
ssh user@target-vm

Then, on the VM:

# 4. Install the a10e CLI and install from the local directory
sudo install -m 0755 ~/a10e-dist/cli/a10e-linux-amd64 /usr/local/bin/a10e # a10e-linux-arm64 on arm64 hosts
sudo mv ~/a10e-dist /opt/a10e-dist
sudo chown -R root:root /opt/a10e-dist
sudo a10e install --source /opt/a10e-dist --channel stable

The first run pauses with exit code 6, asking for JWT_SECRET:

openssl rand -hex 32 # copy the output
sudo sh -c 'echo "JWT_SECRET=<paste the output here>" > /opt/a10e/shared/.env'
sudo chmod 0600 /opt/a10e/shared/.env
sudo a10e install --source /opt/a10e-dist --channel stable # run again to finish

Once it completes, confirm it’s up:

a10e status
curl -fsS http://127.0.0.1:8080/v1/healthcheck

See Bundle Install Reference for where releases live (bucket, object layout, manifest format, signing key) and the prerequisites for the download machine and target host, both assumed from here on.

Follow Bundle Install Reference → Download the release files and → Verify what you downloaded on a machine with bucket access. That leaves a $DIST directory (for example ./a10e-dist) containing the verified manifest.json, its signature, the CLI binaries, and the Connector bundle for your chosen $VERSION.

# from the download machine — the CLI is already inside $DIST/cli/
scp -r "$DIST" user@target-host:~/

On the target host, install the CLI:

sudo install -m 0755 ~/a10e-dist/cli/a10e-linux-amd64 /usr/local/bin/a10e # a10e-linux-arm64 on arm64 hosts
a10e --version

Confirm host prerequisites:

uname -m # x86_64 -> linux/amd64, aarch64 -> linux/arm64
systemctl is-system-running # "running" or "degraded" is fine
sudo docker info --format '{{.OSType}} {{.ServerVersion}}'

Install from the local directory with the CLI

Section titled “Install from the local directory with the CLI”

--source makes the CLI read manifest.json, its signature, and the bundle from a local directory instead of the bucket. No AWS credentials are needed on the host. The CLI remembers the directory’s absolute path in /etc/a10e/config.json for later upgrades, so keep it somewhere stable and root-owned:

sudo mv ~/a10e-dist /opt/a10e-dist
sudo chown -R root:root /opt/a10e-dist

First run — creates the layout and pauses for JWT_SECRET

Section titled “First run — creates the layout and pauses for JWT_SECRET”
sudo a10e install --source /opt/a10e-dist --channel stable
# or pin a version:
sudo a10e install --source /opt/a10e-dist --version 1.2.0

The CLI verifies the manifest signature, validates the manifest, checks the bundle’s signature and SHA-256, extracts it under /opt/a10e/releases/<version>/, stores the signed manifest under /opt/a10e/verified/<version>/, links <release>/.env to the shared /opt/a10e/shared/.env, and creates that shared file (mode 0600) with one empty line per required key.

The very first install then stops with exit code 6:

environment required: set JWT_SECRET in /opt/a10e/shared/.env and rerun the same command

This is expected — nothing has started yet, and the verified release is kept for the rerun.

openssl rand -hex 32 # copy the output
sudo nano /opt/a10e/shared/.env # or sudoedit

Make the file read:

JWT_SECRET=<the 64 hex characters you generated>

Optional keys you can add now (one KEY=value per line; no shell expansion, no inline comments):

Key Purpose
CORS_ALLOWED_ORIGINS Add the host’s public address (e.g. http://connector.example.internal:3000) if browsers reach the dashboard remotely.
A10E_DB_DSN Use your own PostgreSQL instead of the bundled container.
DOCKER_HOST Non-default container runtime socket.
A10E_KEYSTORE_PATH / A10E_KEYSTORE_PASSWORD Needed only if datasources use the java-keystore secret backend: the absolute path of an existing JKS keystore and its password. Both are required, or the backend isn’t registered. See Vaults for the keystore format and an example of creating one.
A10E_DEIDENTIFY_SECRET_KEY Key used to mask sampled data during catalog scans (e.g. openssl rand -hex 32). Automatic catalog scans stay off until it’s set, and it must never change once scans have run — see Catalog Scanning.
A10E_PROXY_PASSWORD_KEY Turns on the Data Proxy request type. A base64-encoded 32-byte key (e.g. openssl rand -base64 32) that encrypts the passwords the proxy stores. Without it the request wizard shows Data Proxy as “Proxy password key is not configured”; Data Enclave requests are unaffected. Keep it stable once proxy requests exist.
A10E_RISK_POLICY_PATH Turns on risk scoring. The absolute path of a TOML file of thresholds, for example [medium] with sources = 2 and fields = 8, and [high] with sources = 3 and fields = 15. Without it the wizard shows “Risk policy is not configured” and the dashboard shows no risk level on requests. Both banners are informational and never block a request.
A10E_PORT / A10E_DASHBOARD_PORT Move the API/dashboard off 8080/3000 — see Bundle Install Reference → Changing the API and dashboard ports. The same settings can instead live in /etc/a10e/config.toml, outside .env entirely — see Persistent Platform Configuration.

Keep the file root-owned with mode 0600:

sudo chown root:root /opt/a10e/shared/.env && sudo chmod 0600 /opt/a10e/shared/.env

Second run — loads images, activates, and starts

Section titled “Second run — loads images, activates, and starts”
sudo a10e install --source /opt/a10e-dist --channel stable

The CLI loads the Docker image archives shipped in the release, points /opt/a10e/current at the release, and writes and starts a10e.service — see How The Bundle Runs for what that unit and its health polling actually do. On top of that shared behavior, the CLI also copies itself to /usr/local/bin/a10e if needed, records /opt/a10e/state.json, saves the source directory in /etc/a10e/config.json, and enables a10e-update.timer, a daily unattended upgrade from that same local directory.

Keep /opt/a10e-dist in place — the daily timer reads from it. To turn unattended updates off:

sudo systemctl disable --now a10e-update.timer
# CLI view
a10e status
sudo a10e status --json
# systemd
systemctl status a10e.service a10e-bundle.service --no-pager
systemctl list-timers a10e-update.timer
# Containers
sudo docker ps --format 'table {{.Names}}\t{{.Image}}\t{{.Status}}\t{{.Ports}}'
# Endpoints the health check uses
curl -fsS http://127.0.0.1:8080/v1/healthcheck && echo " API OK"
curl -fsS http://127.0.0.1:3000/api/health && echo " Dashboard OK"
# Filesystem
readlink /opt/a10e/current # releases/<version>
ls -la /opt/a10e/releases/<version>/.env # -> ../../shared/.env
sudo ls -l /opt/a10e/shared/.env # -rw------- root root

Open http://<host>:3000 in a browser (if the port isn’t reachable from your network, see Remote Access). On a fresh install the dashboard shows a setup screen: create the first admin there, then sign in. The screen is only offered while no user exists, so don’t create a user from the command line first. If you already did and that user is rejected with “You are not a member of this organization”, see the bundle’s README.md (“First admin”) for re-running env-manager user create-admin, which enrolls the existing user on releases that include the fix. Then continue with Operations: Health Checks & Backups and Secret Isolation for the credential-handling model behind JWT_SECRET and the keystore backend.

journalctl -u a10e.service -u a10e-bundle.service -n 200 --no-pager
journalctl -u a10e-bundle.service -f
Exit code / symptom Likely cause / fix
install exits 2 Credentials or source access. With --source, the directory doesn’t exist, isn’t a directory, or a file named in the manifest is missing at its relative path.
Exits 3 Preflight failure: not root, no systemd, Docker not running, unsupported architecture, or another a10e command is running.
Exits 4 Signature, SHA-256, manifest, or extraction failure. Re-download manifest.json and manifest.json.minisig together and re-verify. Never bypass this.
Exits 5 Activation or health check failed; the CLI restored the previous state. Read journalctl -u a10e-bundle.service. Common causes: ports 8080/3000/5433 in use, Docker can’t start containers, image load failed. See Bundle Install Reference → Changing the API and dashboard ports if you need to move one of them off the default.
Exits 6 JWT_SECRET (or another required key) missing or empty in /opt/a10e/shared/.env. Fill it in and rerun the same command.
Health never passes Curl the two endpoints above. API up but dashboard down: check docker logs of the dashboard container. Neither up: check the journal.
Manifest verification fails right after a release You caught the manifest and its signature mid-update. Re-download both.
CLI checksum fails The cli/ objects are replaced on every CLI release, so the binary and its .sha256 may be from different builds. Re-download both together.
docker load fails Usually disk space. Keep room for the compressed bundle, the expanded release, and any retained releases.

Do not edit anything under /opt/a10e/releases/ or /opt/a10e/verified/. Operator settings belong in /opt/a10e/shared/.env or, for releases that support it, the config overlay at /etc/a10e/config.toml (see Persistent Platform Configuration) — never in the release directory itself. A rollback restores the previous release’s code, not the previous database schema — take a database backup (see Operations) before upgrading if you may need to roll back across a schema change.

Offline install sudo a10e install --source /opt/a10e-dist --channel stable (run twice: first run pauses for JWT_SECRET)

For the bucket layout, signing key, install-root file layout, ports, units, and health endpoints, see Bundle Install Reference → Quick Reference.