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:
- Download the release files (the
a10eCLI,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. - 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.
Install the RHEL version
Section titled “Install the RHEL version”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-rhelIf 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-rhelThe 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.
Quickstart
Section titled “Quickstart”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 locallyexport AWS_REGION=us-west-1export AWS_ACCESS_KEY_ID=...export AWS_SECRET_ACCESS_KEY=...aws s3 sync s3://a10e-releases ./a10e-dist
# 2. Copy everything to the target VMscp -r ./a10e-dist user@target-vm:~/a10e-dist
# 3. SSH into the VMssh user@target-vmThen, on the VM:
# 4. Install the a10e CLI and install from the local directorysudo install -m 0755 ~/a10e-dist/cli/a10e-linux-amd64 /usr/local/bin/a10e # a10e-linux-arm64 on arm64 hostssudo mv ~/a10e-dist /opt/a10e-distsudo chown -R root:root /opt/a10e-distsudo a10e install --source /opt/a10e-dist --channel stableThe first run pauses with exit code 6, asking for JWT_SECRET:
openssl rand -hex 32 # copy the outputsudo sh -c 'echo "JWT_SECRET=<paste the output here>" > /opt/a10e/shared/.env'sudo chmod 0600 /opt/a10e/shared/.envsudo a10e install --source /opt/a10e-dist --channel stable # run again to finishOnce it completes, confirm it’s up:
a10e statuscurl -fsS http://127.0.0.1:8080/v1/healthcheckSee 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.
Download and verify the release files
Section titled “Download and verify the release files”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.
Move the files to the target host
Section titled “Move the files to the target host”# 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 hostsa10e --versionConfirm host prerequisites:
uname -m # x86_64 -> linux/amd64, aarch64 -> linux/arm64systemctl is-system-running # "running" or "degraded" is finesudo 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-distsudo chown -R root:root /opt/a10e-distFirst 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.0The 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 commandThis is expected — nothing has started yet, and the verified release is kept for the rerun.
Fill in the shared environment
Section titled “Fill in the shared environment”openssl rand -hex 32 # copy the outputsudo nano /opt/a10e/shared/.env # or sudoeditMake 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/.envSecond run — loads images, activates, and starts
Section titled “Second run — loads images, activates, and starts”sudo a10e install --source /opt/a10e-dist --channel stableThe 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.timerVerify everything is running
Section titled “Verify everything is running”# CLI viewa10e statussudo a10e status --json
# systemdsystemctl status a10e.service a10e-bundle.service --no-pagersystemctl list-timers a10e-update.timer
# Containerssudo docker ps --format 'table {{.Names}}\t{{.Image}}\t{{.Status}}\t{{.Ports}}'
# Endpoints the health check usescurl -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"
# Filesystemreadlink /opt/a10e/current # releases/<version>ls -la /opt/a10e/releases/<version>/.env # -> ../../shared/.envsudo ls -l /opt/a10e/shared/.env # -rw------- root rootOpen 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.
Logs and troubleshooting
Section titled “Logs and troubleshooting”journalctl -u a10e.service -u a10e-bundle.service -n 200 --no-pagerjournalctl -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.
Quick reference
Section titled “Quick reference”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.