Bundle Install Reference
This page covers what’s common to both ways of installing the Connector from a signed release bundle:
- Standalone Bundle Install (CLI-managed) — the recommended path, using the
a10eCLI. - Manual Bundle Install — the same result, reproduced by hand, for troubleshooting or hosts where the CLI can’t run.
Read this first if you’re installing from a bundle rather than Docker Compose or Kubernetes — those two guides are self-contained and don’t need anything on this page.
Where releases live
Section titled “Where releases live”Releases are published to a private S3 bucket. Your Alien Giraffe contact provides read credentials.
| Setting | Value |
|---|---|
| Bucket | a10e-releases |
| Region | us-west-1 |
| Access | private — read credentials (s3:GetObject, s3:ListBucket) supplied by Alien Giraffe |
| Channel | connector-data-rhel for the RHEL version; otherwise stable unless you were given a different channel name |
Object layout:
manifest.json signed release manifest (updated on every release)manifest.json.minisig detached minisign signature of the manifestreleases/<version>/linux-amd64.tar.gz Connector bundle, immutable once publishedreleases/<version>/linux-amd64.tar.gz.minisigreleases/<version>/linux-arm64.tar.gzreleases/<version>/linux-arm64.tar.gz.minisigcli/a10e-linux-amd64 a10e CLI binaries (always the latest build)cli/a10e-linux-amd64.sha256 SHA-256 checksum of the binarycli/a10e-linux-arm64cli/a10e-linux-arm64.sha256cli/a10e-darwin-arm64 macOS, Apple silicon — for the download/verify machinecli/a10e-darwin-arm64.sha256cli/a10e-darwin-amd64 macOS, Intelcli/a10e-darwin-amd64.sha256manifest.json contains a channels map (for example {"stable": "1.2.0"}) and a versions list. Each version entry names its artifacts per architecture with path, SHA-256, and signature, the lifecycle commands the CLI runs, the health timeout, the environment keys the release requires (currently JWT_SECRET), and the Docker image archives it ships.
The manifest and bundles are signed with minisign. The public key, also embedded in the a10e CLI, is:
untrusted comment: minisign public key: D36595CDE05E89E0RWTgiV7gzZVl0xN1tE9wj/pehcPeDC0MgVSKwxkrdjbcgbsTd19c0UfxThe CLI binaries are not minisign-signed; each ships with a .sha256 checksum file instead. The cli/ objects carry no version in their key — the prefix always holds the newest build — so a10e --version after download is how you record which CLI you installed.
Prerequisites
Section titled “Prerequisites”On the machine you download from (typically your workstation):
awsCLI v2,jq,minisign, andsha256sum(orshasum -a 256on macOS).- The bucket read credentials, exported as
AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY(plusAWS_SESSION_TOKENif temporary). If given in the CLI’s ownA10E_KEY=ACCESS_KEY_ID:SECRET_ACCESS_KEYform, the part before the colon is the access key ID and the part after is the secret.
On the target host:
- Ubuntu 22.04, Ubuntu 24.04, or Debian 12, on amd64 or arm64, booted with systemd — or RHEL 8 (validated on RHEL 8.10) on amd64 or arm64, booted with systemd, if you’re using Podman (see below).
- Docker Engine installed and running as root (
sudo docker infosucceeds), or Podman ≥4.7 withpodman.socketenabled (sudo podman infosucceeds). The connector auto-detects whichever is present; see Manual Bundle Install → Using Podman instead of Docker for the RHEL-family install steps and the systemd-unit differences. Thea10eCLI itself doesn’t support Podman yet (aliengiraffe/cli#8), so Standalone Bundle Install’s CLI-managed path still requires Docker until that lands — use Manual Bundle Install on a Podman-only host in the meantime. - Root access (
sudo). jq, if you install with Manual Bundle Install: its step 6 reads the image list from the manifest with it. A stock RHEL 8 host doesn’t have it; install it withsudo dnf install -y jq(RHEL 8) orsudo apt-get install -y jq(Ubuntu/Debian). Thea10eCLI doesn’t need it.- Free disk space for the compressed bundle plus the expanded release — several GiB.
- Ports 8080 (API), 3000 (dashboard), and 5433 (bundled PostgreSQL, loopback only) free — both 8080 and 3000 can be moved if they collide with something else, or you’d rather firewall a well-known port instead; see Changing the API and dashboard ports.
Linux builds (amd64, arm64) run on the target host. macOS builds are for the workstation, where they can validate the manifest; install, upgrade, rollback, and status only run on the Linux host.
Download the release files
Section titled “Download the release files”Run these on the download machine.
export AWS_REGION=us-west-1export AWS_ACCESS_KEY_ID=...export AWS_SECRET_ACCESS_KEY=...# export AWS_SESSION_TOKEN=... # only if given temporary credentials
BUCKET=a10e-releasesCHANNEL=stable # use connector-data-rhel for the RHEL versionDIST=$PWD/a10e-dist # local distribution rootmkdir -p "$DIST"Manifest and its signature
Section titled “Manifest and its signature”aws s3 cp "s3://$BUCKET/manifest.json" "$DIST/manifest.json"aws s3 cp "s3://$BUCKET/manifest.json.minisig" "$DIST/manifest.json.minisig"Download the two objects back to back. During a release the manifest and its signature are replaced one after the other, so there’s a brief moment when they don’t match. If verification fails, re-download both.
Pick the version
Section titled “Pick the version”VERSION=$(jq -r --arg c "$CHANNEL" '.channels[$c]' "$DIST/manifest.json")echo "Channel $CHANNEL -> $VERSION"
# Or pin a specific version listed under .versions[].version:# VERSION=1.2.0
jq --arg v "$VERSION" '.versions[] | select(.version == $v)' "$DIST/manifest.json"Keep the same relative paths locally — the CLI’s --source mode and the manual steps both depend on it.
Connector bundle and signature
Section titled “Connector bundle and signature”Mirror every architecture of the version:
aws s3 sync "s3://$BUCKET/releases/$VERSION/" "$DIST/releases/$VERSION/"Or only your target host’s architecture, driven by the manifest:
ARCH=linux/amd64 # or linux/arm64for key in $(jq -r --arg v "$VERSION" --arg a "$ARCH" \ '.versions[] | select(.version == $v) | .artifacts[$a] | .path, .signature' "$DIST/manifest.json"); do mkdir -p "$DIST/$(dirname "$key")" aws s3 cp "s3://$BUCKET/$key" "$DIST/$key"doneThe a10e CLI
Section titled “The a10e CLI”mkdir -p "$DIST/cli"
# Target host (match its architecture)for f in a10e-linux-amd64 a10e-linux-amd64.sha256; do # or a10e-linux-arm64 aws s3 cp "s3://$BUCKET/cli/$f" "$DIST/cli/$f"done
# Your workstation, optionalcase "$(uname -s)-$(uname -m)" in Darwin-arm64) CLI=a10e-darwin-arm64 ;; Darwin-x86_64) CLI=a10e-darwin-amd64 ;; Linux-x86_64) CLI=a10e-linux-amd64 ;; Linux-aarch64) CLI=a10e-linux-arm64 ;;esacaws s3 cp "s3://$BUCKET/cli/$CLI" "$DIST/cli/$CLI"aws s3 cp "s3://$BUCKET/cli/$CLI.sha256" "$DIST/cli/$CLI.sha256"Verify what you downloaded
Section titled “Verify what you downloaded”PUBKEY=RWTgiV7gzZVl0xN1tE9wj/pehcPeDC0MgVSKwxkrdjbcgbsTd19c0Ufxcd "$DIST"
# 1. CLI binaries against their SHA-256 checksum filesfor bin in cli/a10e-*; do case "$bin" in *.sha256) continue ;; esac expected=$(awk '{print $1}' "$bin.sha256") echo "$expected $bin" | sha256sum -c - && chmod 0755 "$bin"donecli/$CLI --version
# 2. Manifest signature (must pass before anything inside it is trusted)minisign -V -P "$PUBKEY" -m manifest.json -x manifest.json.minisig
# 3. Manifest structure, using the CLI (no root or credentials needed)cli/$CLI validate-manifest manifest.json
# 4. Each bundle: signature and the SHA-256 recorded in the manifestfor a in $(jq -r --arg v "$VERSION" '.versions[] | select(.version == $v) | .artifacts | keys[]' manifest.json); do path=$(jq -r --arg v "$VERSION" --arg a "$a" '.versions[] | select(.version == $v) | .artifacts[$a].path' manifest.json) sig=$(jq -r --arg v "$VERSION" --arg a "$a" '.versions[] | select(.version == $v) | .artifacts[$a].signature' manifest.json) sum=$(jq -r --arg v "$VERSION" --arg a "$a" '.versions[] | select(.version == $v) | .artifacts[$a].sha256' manifest.json) [ -f "$path" ] || { echo "skip $a (not downloaded)"; continue; } minisign -V -P "$PUBKEY" -m "$path" -x "$sig" echo "$sum $path" | sha256sum -c -doneEvery check should report OK (checksums) or “Signature and comment signature verified” (minisign). If anything fails, stop: re-download the affected files, and if the failure persists, contact Alien Giraffe support. Never bypass a signature check.
Once everything verifies, move on to installing: Standalone Bundle Install to install via the CLI, or Manual Bundle Install to reproduce the install by hand.
How The Bundle Runs
Section titled “How The Bundle Runs”Both install paths converge on the same runtime, whether the a10e CLI wrote it for you or you wrote it by hand:
a10e.serviceis aoneshotsystemd unit. ItsExecStartrunsenv-manager bundle startand exits; itsExecStoprunsbundle stop.bundle startregisters and starts a second unit,a10e-bundle.service, which is the actual long-running Connector. It loads any Docker image still missing, starts the bundled PostgreSQL (data in thea10e-bundle-pgdatavolume, credential in/opt/a10e/shared/env-manager/postgres-password) and the dashboard container, runs database migrations, then serves the API on port 8080.- Whichever path creates it, the CLI (or you, in the manual path) then polls
env-manager bundle healthonce a second for up to 180 seconds, waiting for both the API and dashboard to respond before considering the install complete.
The CLI-managed path additionally copies itself to /usr/local/bin/a10e, records the install in /etc/a10e/config.json, and enables a daily a10e-update.timer for unattended upgrades — none of which a manual install sets up on its own (see Bringing the host under CLI management later if you want those afterward).
Changing the API and dashboard ports
Section titled “Changing the API and dashboard ports”Both defaults — 8080 for the API, 3000 for the dashboard — can be moved to another host port. This is the bundle-specific mechanism; it’s separate from (and doesn’t need) a reverse proxy in front, though it composes fine with one, including publishing on a well-known port like 443 or 8443 instead of opening a firewall exception for 3000/8080 directly.
Two supported mechanisms, both restart-and-forget across upgrades — pick whichever fits how you manage the host:
Set A10E_PORT (API) and/or A10E_DASHBOARD_PORT (dashboard) in the shared .env:
echo 'A10E_PORT=8443' >> /opt/a10e/shared/.envecho 'A10E_DASHBOARD_PORT=8444' >> /opt/a10e/shared/.envsystemctl restart a10e.serviceshared/.env is exactly the file the CLI creates once and never overwrites — the same one that already carries JWT_SECRET, A10E_DB_DSN, and CORS_ALLOWED_ORIGINS unchanged across every a10e install/upgrade (see Standalone Bundle Install → Fill in the shared environment).
Or set the same two settings in the operator config overlay at /etc/a10e/config.toml, a file dedicated to persistent platform settings rather than secrets — see Persistent Platform Configuration for the full precedence, merge rules, and a settings reference beyond just ports. .env keeps winning over the overlay if both are set, so pick one per setting rather than splitting a single port between them.
The dashboard container’s internal port always stays 3000 — only the host-side published port changes, so nothing else needs to know about it. bundle health probes http://127.0.0.1:<dashboard-port>/api/health, using whatever the resolved dashboard port is, so it always matches what was actually published.
Quick Reference
Section titled “Quick Reference”Bucket / region s3://a10e-releases us-west-1 (private; credentials supplied by Alien Giraffe)Release objects manifest.json, manifest.json.minisig, releases/<ver>/linux-<arch>.tar.gz{,.minisig}CLI binaries cli/a10e-{linux,darwin}-{amd64,arm64}{,.sha256} (latest build; SHA-256 checksum, not minisign)Signing public key RWTgiV7gzZVl0xN1tE9wj/pehcPeDC0MgVSKwxkrdjbcgbsTd19c0UfxInstall root /opt/a10e/{releases,verified,shared,current,state.json}Config /etc/a10e/config.json (CLI-managed installs only)Shared env /opt/a10e/shared/.env (root, 0600, JWT_SECRET required)Postgres credential /opt/a10e/shared/env-manager/postgres-passwordPostgres data Docker volume a10e-bundle-pgdata (default /var/lib/docker/volumes/a10e-bundle-pgdata/_data)Containers a10e-bundle-postgres · a10e-bundle-dashboardUnits a10e.service (oneshot) -> a10e-bundle.service (Connector) a10e-update.timer / a10e-update.service (daily unattended upgrade, CLI-managed installs only)Ports 8080 API · 3000 dashboard · 5433 PostgreSQL (127.0.0.1 only)Health endpoints http://127.0.0.1:8080/v1/healthcheck · http://127.0.0.1:3000/api/health