jmcqueen/netanalyzer
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
netanalyzer/docker/remote-agent/deploy/README.md
Joseph McQueen 0506f39bf3 fix(deploy): install.sh always docker-loads so stale wrong-arch images can't hide the shipped tarball 
Previously install.sh short-circuited with "Image ... already present -
skipping load" whenever a tag with the same version already existed in
Docker. That optimization was actively harmful: if an earlier deploy
attempt had loaded a wrong-arch (e.g. arm64) image at the same tag, we'd
never load the corrected tarball in the current ZIP and the arch check
would keep failing against the stale image forever.

docker load reassigns the tag atomically to whatever is in the tarball and
is a fast no-op when the layers are already present, so unconditional load
is both safe and self-healing.

install.sh now also prints the loaded image id + arch and, on mismatch,
tells the operator to `git pull` on the build host before re-running
package.sh so they pick up the buildx/binfmt fixes.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-06 10:12:08 -04:00

4.4 KiB
Raw Blame History

StoreHealthAnalyzer Remote Agent — Deploy Bundle

This ZIP is a self-contained deployment bundle for the StoreHealthAnalyzer remote agent. Extract it, run install.sh, fill in your .env, and the agent will start as a Docker container.

What's in the bundle

File Purpose
sha-remote-agent-<version>.tar.gz The Docker image, saved via docker save.
docker-compose.yml Runtime-only compose file (no build step; references the loaded image).
install.sh Verifies checksum, loads the image, seeds .env, starts the container.
.env.example Template — copied to .env on first run for you to fill in.
SHA256SUMS Integrity check for the image tarball.
VERSION Plain-text version marker used by install.sh and docker-compose.yml.
README.md This file.

Prerequisites (on the remote host)

  • Docker 20.10+ with the daemon running.
  • Docker Compose — either the modern docker compose plugin (v2) or the legacy docker-compose binary. install.sh auto-detects.
  • Whichever user runs install.sh needs permission to talk to the Docker daemon (member of the docker group, or run under sudo).
  • Outbound network access from the host to:
    • The main StoreHealthAnalyzer server (WS_URL).
    • The internal APIs the agent proxies for (SIW, MDM, etc.).

Install / start

unzip sha-remote-agent-<version>.zip
cd sha-remote-agent-<version>
./install.sh

On the first run install.sh will:

  1. Verify the SHA-256 of the image tarball against SHA256SUMS.
  2. Load the image into Docker (skipped on subsequent runs if the image is already present).
  3. Copy .env.example → .env and stop, asking you to fill it in.

Fill in .env:

vi .env    # set WS_URL and WS_TOKEN

Then re-run:

./install.sh

That last run will start the container (docker compose up -d) and print the log-tail command.

Day-to-day operations

docker compose logs -f              # tail the agent logs
docker compose ps                   # show container status
docker compose restart              # cycle it
docker compose down                 # stop and remove the container
docker compose up -d                # bring it back up

Healthy startup looks like:

🔄 Connecting to wss://.../ws...
✅ Remote Agent connected to StoreHealthAnalyzer

Upgrading

When you receive a newer ZIP:

# Optional: back up your existing config
cp -a <old-version-folder>/.env ./sha-remote-agent-<new-version>-env.bak

# Stop the old container
cd <old-version-folder> && docker compose down && cd ..

# Extract and start the new one
unzip sha-remote-agent-<new-version>.zip
cp <old-version-folder>/.env sha-remote-agent-<new-version>/.env
cd sha-remote-agent-<new-version>
./install.sh

The old image stays in Docker's local cache until you docker image prune it — handy if you need to roll back quickly.

Troubleshooting

  • "Cannot talk to the Docker daemon" — either Docker isn't running or your user isn't in the docker group. Try sudo ./install.sh or add yourself to the group: sudo usermod -aG docker $USER and log back in.

  • "Checksum verification FAILED" — the ZIP was corrupted in transit. Re-transfer.

  • "exec /sbin/tini: exec format error" or "Image architecture does not match this host" — the ZIP was built for the wrong CPU architecture (typically an Apple Silicon Mac produced an arm64 image for an x86_64 Linux host). install.sh catches this and prints the exact rebuild command; ask your build operator to git pull first (to pick up the fixed cross-arch build) and then run:

    ./docker/remote-agent/package.sh --platform linux/amd64

    (or linux/arm64 if this host is ARM — run uname -m to check: x86_64 → linux/amd64, aarch64 → linux/arm64.)

    Note that install.sh always re-runs docker load on the bundled tarball, so a stale image left from an earlier wrong-arch attempt at the same version tag will be transparently replaced when you install a corrected bundle — no need to docker rmi by hand.

  • Agent connects, then disconnects immediately — WS_TOKEN doesn't match the server. Fix in .env, then docker compose restart.

  • Agent never connects — check WS_URL (correct hostname, correct scheme ws:// vs wss://) and that there's no firewall between this host and the server.