Skip to content

Bundle Install Reference

This page covers what’s common to both ways of installing the Connector from a signed release bundle:

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.

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 manifest
releases/<version>/linux-amd64.tar.gz Connector bundle, immutable once published
releases/<version>/linux-amd64.tar.gz.minisig
releases/<version>/linux-arm64.tar.gz
releases/<version>/linux-arm64.tar.gz.minisig
cli/a10e-linux-amd64 a10e CLI binaries (always the latest build)
cli/a10e-linux-amd64.sha256 SHA-256 checksum of the binary
cli/a10e-linux-arm64
cli/a10e-linux-arm64.sha256
cli/a10e-darwin-arm64 macOS, Apple silicon — for the download/verify machine
cli/a10e-darwin-arm64.sha256
cli/a10e-darwin-amd64 macOS, Intel
cli/a10e-darwin-amd64.sha256

manifest.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: D36595CDE05E89E0
RWTgiV7gzZVl0xN1tE9wj/pehcPeDC0MgVSKwxkrdjbcgbsTd19c0Ufx

The 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.

On the machine you download from (typically your workstation):

  • aws CLI v2, jq, minisign, and sha256sum (or shasum -a 256 on macOS).
  • The bucket read credentials, exported as AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY (plus AWS_SESSION_TOKEN if temporary). If given in the CLI’s own A10E_KEY=ACCESS_KEY_ID:SECRET_ACCESS_KEY form, 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 info succeeds), or Podman ≥4.7 with podman.socket enabled (sudo podman info succeeds). 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. The a10e CLI 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 with sudo dnf install -y jq (RHEL 8) or sudo apt-get install -y jq (Ubuntu/Debian). The a10e CLI 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.

Run these on the download machine.

export AWS_REGION=us-west-1
export AWS_ACCESS_KEY_ID=...
export AWS_SECRET_ACCESS_KEY=...
# export AWS_SESSION_TOKEN=... # only if given temporary credentials
BUCKET=a10e-releases
CHANNEL=stable # use connector-data-rhel for the RHEL version
DIST=$PWD/a10e-dist # local distribution root
mkdir -p "$DIST"
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.

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.

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/arm64
for 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"
done
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, optional
case "$(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 ;;
esac
aws s3 cp "s3://$BUCKET/cli/$CLI" "$DIST/cli/$CLI"
aws s3 cp "s3://$BUCKET/cli/$CLI.sha256" "$DIST/cli/$CLI.sha256"
PUBKEY=RWTgiV7gzZVl0xN1tE9wj/pehcPeDC0MgVSKwxkrdjbcgbsTd19c0Ufx
cd "$DIST"
# 1. CLI binaries against their SHA-256 checksum files
for 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"
done
cli/$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 manifest
for 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 -
done

Every 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.

Both install paths converge on the same runtime, whether the a10e CLI wrote it for you or you wrote it by hand:

  • a10e.service is a oneshot systemd unit. Its ExecStart runs env-manager bundle start and exits; its ExecStop runs bundle stop.
  • bundle start registers 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 the a10e-bundle-pgdata volume, 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 health once 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).

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/.env
echo 'A10E_DASHBOARD_PORT=8444' >> /opt/a10e/shared/.env
systemctl restart a10e.service

shared/.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.

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/pehcPeDC0MgVSKwxkrdjbcgbsTd19c0Ufx
Install 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-password
Postgres data Docker volume a10e-bundle-pgdata (default /var/lib/docker/volumes/a10e-bundle-pgdata/_data)
Containers a10e-bundle-postgres · a10e-bundle-dashboard
Units 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