0506f39bf3
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>
125 lines
4.4 KiB
Markdown
125 lines
4.4 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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`:
|
|
|
|
```bash
|
|
vi .env # set WS_URL and WS_TOKEN
|
|
```
|
|
|
|
Then re-run:
|
|
|
|
```bash
|
|
./install.sh
|
|
```
|
|
|
|
That last run will start the container (`docker compose up -d`) and print
|
|
the log-tail command.
|
|
|
|
## Day-to-day operations
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
# 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.
|