Skip to content

Manual Bundle Install (No CLI)

This guide reproduces what the a10e CLI does during a bundle install, one command at a time. Use it for troubleshooting, or on a host where the CLI itself can’t run.

Run everything as root (sudo -i) and substitute your own version and architecture. This assumes you’ve already downloaded and verified the release files — the manifest, its signature, and the bundle tarball must already be present locally. See Bundle Install Reference for the target host’s prerequisites (OS, container runtime, jq, ports, disk space) if you haven’t checked those yet.

The steps below are written for Docker. If your target host runs Podman instead (common on RHEL-family hosts, where Docker often isn’t installed), everything is identical except loading the images in step 6 and the systemd unit in step 8 — see Using Podman instead of Docker below step 6.

VERSION=1.2.0
ARCH=amd64 # or arm64
DIST=/root/a10e-dist # where you copied the downloaded files
ROOT=/opt/a10e
mkdir -p "$ROOT/releases" "$ROOT/verified/$VERSION" "$ROOT/shared"
chmod 0700 "$ROOT/releases"

2. Extract the bundle into a staging directory

Section titled “2. Extract the bundle into a staging directory”
STAGE=$(mktemp -d "$ROOT/releases/.stage-XXXXXX")
mkdir -p "$STAGE/payload"
tar -xzf "$DIST/releases/$VERSION/linux-$ARCH.tar.gz" -C "$STAGE/payload" --no-same-owner
ls "$STAGE/payload"
# bin/ images/ a10e.toml env.example .env.defaults README.md VERSION
test -x "$STAGE/payload/bin/env-manager" && echo "lifecycle binary OK"

Bundles are flat (every path is relative to the release root) and contain no .env and no symlinks, so extracting as root is safe.

3. Keep the verified manifest beside the release

Section titled “3. Keep the verified manifest beside the release”
install -m 0600 "$DIST/manifest.json" "$ROOT/verified/$VERSION/manifest.json"
install -m 0600 "$DIST/manifest.json.minisig" "$ROOT/verified/$VERSION/manifest.json.minisig"
Section titled “4. Create the shared .env and link it into the release”
if [ ! -f "$ROOT/shared/.env" ]; then
umask 077
printf 'JWT_SECRET=%s\n' "$(openssl rand -hex 32)" > "$ROOT/shared/.env"
fi
# Masks sampled data during catalog scans. Generate it once and never change it.
grep -q '^A10E_DEIDENTIFY_SECRET_KEY=' "$ROOT/shared/.env" ||
printf 'A10E_DEIDENTIFY_SECRET_KEY=%s\n' "$(openssl rand -hex 32)" >> "$ROOT/shared/.env"
chmod 0600 "$ROOT/shared/.env"
ln -s ../../shared/.env "$STAGE/payload/.env"

A10E_DEIDENTIFY_SECRET_KEY is not optional for catalog scans: without it the scan scheduler stays off and a manual catalog scan exits before touching any datasource. Keep it stable once scans have run (see Scan Your Catalog).

If browsers reach the dashboard remotely, set CORS_ALLOWED_ORIGINS now to the host’s public address (for example CORS_ALLOWED_ORIGINS=http://connector.example.internal:3000). Add any other optional keys (see Standalone Bundle Install) to $ROOT/shared/.env now. The release reads .env first and its own .env.defaults second, so shared values take precedence.

mv "$STAGE/payload" "$ROOT/releases/$VERSION"
rmdir "$STAGE"
cd "$ROOT/releases/$VERSION"
for img in $(jq -r --arg v "$VERSION" '.versions[] | select(.version == $v) | .images[]' "$DIST/manifest.json"); do
/usr/bin/docker load --input "$img"
done
docker images | grep -E "env-dashboard|env-enzo|pgvector"

Image tags carry the version and architecture, for example env-dashboard:1.2.0-linux-amd64. A data- or both-profile release ships an env-enzo image; an ai-profile release does not.

The connector auto-detects its container runtime and fully supports Podman ≥4.7 — this has been validated end to end on RHEL 8.10, including the bundled PostgreSQL, the dashboard, and an env-enzo container brought up by an activated request. RHEL 8’s own default AppStream repo ships a recent-enough Podman, no third-party repo needed:

sudo dnf install -y podman # RHEL 8.10 ships 4.9.4, well above the 4.7 floor
sudo systemctl enable --now podman.socket
sudo podman info --format '{{.Host.RemoteSocket.Path}}' # /run/podman/podman.sock

Then load the images with podman load instead of docker load:

cd "$ROOT/releases/$VERSION"
for img in $(jq -r --arg v "$VERSION" '.versions[] | select(.version == $v) | .images[]' "$DIST/manifest.json"); do
podman load --input "$img"
done
podman images | grep -E "env-dashboard|env-enzo|pgvector"

Continue with step 7 as written. Step 8’s systemd unit needs two Podman-specific changes, covered there.

ln -s "releases/$VERSION" "$ROOT/.current-next"
mv -T "$ROOT/.current-next" "$ROOT/current" # atomic replace of the symlink
readlink "$ROOT/current"

This is the same unit the CLI writes, with the release path filled in. The lifecycle commands receive only PATH, HOME, and LANG; they read their configuration from the release’s .env.

If the API or dashboard need to run on a non-default port (8080/3000), see Bundle Install Reference → Changing the API and dashboard ports — set A10E_PORT/A10E_DASHBOARD_PORT in the shared .env from step 4, or persist the same settings outside .env in /etc/a10e/config.toml (see Persistent Platform Configuration); either way it needs no change to the unit below and survives future upgrades.

cat > /etc/systemd/system/a10e.service <<EOF
[Unit]
Description=a10e connector
Requires=docker.service
After=docker.service network-online.target
[Service]
Type=oneshot
RemainAfterExit=yes
WorkingDirectory=$ROOT/releases/$VERSION
ExecStart=/usr/bin/env -i PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin HOME=/root LANG=C.UTF-8 $ROOT/releases/$VERSION/bin/env-manager bundle start
ExecStop=/usr/bin/env -i PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin HOME=/root LANG=C.UTF-8 $ROOT/releases/$VERSION/bin/env-manager bundle stop
TimeoutStartSec=180
TimeoutStopSec=180
Environment="PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" "HOME=/root" "LANG=C.UTF-8"
StandardOutput=journal
StandardError=journal
[Install]
WantedBy=multi-user.target
EOF
chmod 0644 /etc/systemd/system/a10e.service
systemctl daemon-reload
systemctl enable a10e.service
systemctl start a10e.service
# Poll as the CLI does: once a second, up to 180 seconds
cd "$ROOT/releases/$VERSION"
for i in $(seq 1 180); do
if /usr/bin/env -i PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin HOME=/root LANG=C.UTF-8 \
./bin/env-manager bundle health >/dev/null 2>&1; then
echo "healthy after ${i}s"; break
fi
sleep 1
done

If you’re using Podman, the health check runs under env -i, which drops your shell’s environment, so add the same DOCKER_HOST as the unit in step 8. Without it the check can look at the wrong runtime and never report healthy:

for i in $(seq 1 180); do
if /usr/bin/env -i PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin HOME=/root LANG=C.UTF-8 \
DOCKER_HOST=unix:///run/podman/podman.sock ./bin/env-manager bundle health >/dev/null 2>&1; then
echo "healthy after ${i}s"; break
fi
sleep 1
done

See How The Bundle Runs for what bundle start and a10e-bundle.service do from here — loading any remaining images, starting the bundled PostgreSQL and dashboard, running migrations, and serving the API on port 8080.

# systemd
systemctl status a10e.service a10e-bundle.service --no-pager
# Containers (podman ps, if you're using Podman)
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
ls -l /opt/a10e/shared/.env # -rw------- root root

If you install the CLI on this host later, a10e status and a10e status --json work too.

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
Symptom Likely cause / fix
docker load / podman load fails at step 6 Usually disk space. Keep room for the compressed bundle, the expanded release, and any retained releases.
systemctl start a10e.service fails immediately Docker/Podman isn’t running, or the unit is already active. Check systemctl status docker.service (Docker) or systemctl status podman.socket (Podman), and journalctl -u a10e.service.
Health polling loop in step 9 never prints “healthy” Ports 8080/3000/5433 already in use, the container runtime can’t start containers, or an image failed to load. Check journalctl -u a10e-bundle.service and docker ps -a / podman ps -a.
a10e-bundle.service logs pick Docker when you meant Podman DOCKER_HOST wasn’t visible to the unit. Confirm /run/podman/podman.sock exists (systemctl status podman.socket) and that step 8’s unit — both the env -i invocations and the Environment= line — includes DOCKER_HOST=unix:///run/podman/podman.sock, then systemctl daemon-reload && systemctl restart a10e.service.
Health never passes but the loop exits Curl the two endpoints above by hand. API up but dashboard down: check docker logs of the dashboard container. Neither up: check the journal.
env-manager: command not found or not executable The bundle didn’t extract correctly, or $STAGE/payload/bin/env-manager isn’t executable — re-extract the tarball and re-check with test -x.
.env values not taking effect Confirm $ROOT/releases/$VERSION/.env is a symlink to ../../shared/.env (step 4) and that $ROOT/shared/.env has no shell expansion or inline comments.

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 (relinking /opt/a10e/current to a previous release directory) 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.

An upgrade repeats the install with the new release, on the same host. The shared .env, the secret files you reference from datasources, the bundled PostgreSQL volume and its credential live outside the release directories, so they carry over untouched. Nothing here needs the CLI.

  1. Download and verify the new release files, and set VERSION to the new version. Keep ROOT, ARCH and DIST as before.

  2. Back up the database while the service is still running. Run the pg_dump from Operations: Health Checks & Backups (on Podman, podman exec in place of docker exec), and copy /opt/a10e/shared/.env and /opt/a10e/shared/env-manager/postgres-password beside it:

    install -d -m 0700 /var/backups/a10e
    podman exec a10e-bundle-postgres \
    pg_dump -U a10e -d a10e_db --format=custom --no-owner \
    > /var/backups/a10e/a10e_db-pre-$VERSION.dump
    cp -p /opt/a10e/shared/.env /opt/a10e/shared/env-manager/postgres-password /var/backups/a10e/
  3. Repeat steps 1 to 3 (layout, extract, manifest) and step 5 (finalize) as written. Step 4 is safe to run again: it doesn’t overwrite an existing .env or A10E_DEIDENTIFY_SECRET_KEY, and only links the shared .env into the new release. Then load the new images (step 6, with podman load on Podman).

  4. Stop the running release: systemctl stop a10e.service.

  5. Activate the new release (step 7) and write the systemd unit again (step 8, the Podman variant if you use Podman). The unit contains the release path, so it must be rewritten for every version. Then run systemctl daemon-reload and systemctl start a10e.service, and wait for health as in step 9.

  6. Confirm the version, as described below.

Database migrations run when the service starts. The journal shows database migrations applied with the schema version once they finish (journalctl -u a10e-bundle.service | grep 'database migrations applied').

Confirm the running version:

readlink /opt/a10e/current # releases/<new version>
podman images | grep -E "env-dashboard|env-enzo" # tags carry the version
podman ps --format 'table {{.Names}}\t{{.Image}}' # the dashboard runs the new tag

An env-enzo container that belongs to a request already active before the upgrade isn’t restarted: it keeps running the old image until the request is activated again.

To roll back, relink /opt/a10e/current to the previous release, rewrite the unit for its path and restart. That restores the previous code only. If the new release applied a database migration, the previous release may not run on the migrated database: restore the dump from step 2 first (see Restoring a logical backup).

Bringing the host under CLI management later

Section titled “Bringing the host under CLI management later”

If you install the CLI afterwards:

install -m 0755 "$DIST/cli/a10e-linux-$ARCH" /usr/local/bin/a10e

a10e status will report the active release, but upgrade needs /etc/a10e/config.json, which only a CLI-driven install writes. To bring a manually-installed host under CLI management:

  1. Stop and disable a10e.service and a10e-bundle.service.
  2. Remove /opt/a10e/current and the release directory.
  3. Keep /opt/a10e/shared/ (this preserves JWT_SECRET, the PostgreSQL credential, and all application data).
  4. Run the Standalone Bundle Install path A steps.