# wbxStoreProvision Remote Agent — Deploy Bundle

This ZIP is a self-contained deployment bundle for the wbxStoreProvision
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 |
| --- | --- |
| `wbxprov-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 wbxStoreProvision bot (`WS_URL`).
  - Store Info Web (the internal API the agent proxies for).

## Install / start

```bash
unzip wbxprov-remote-agent-<version>.zip
cd wbxprov-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 (a fast no-op on subsequent runs).
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 wbxStoreProvision
```

## Upgrading

When you receive a newer ZIP:

```bash
# Optional: back up your existing config
cp -a <old-version-folder>/.env ./wbxprov-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 wbxprov-remote-agent-<new-version>.zip
cp <old-version-folder>/.env wbxprov-remote-agent-<new-version>/.env
cd wbxprov-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.

## Coexistence with the netanalyzer agent

This bundle uses distinct image and container names
(`wbxprov-remote-agent`), so it can run on the same host as
`sha-remote-agent` (netanalyzer's agent) without any conflict. Keep the
two deploy folders separate — each has its own `.env` pointing at its own
server.

## 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 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 bot's `WS_TOKEN`. 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 bot.
- **Requests to SIW fail from the agent's logs** — the container needs
  direct network reachability to SIW. If SIW lives on the host's local
  network and the container can't reach it, uncomment `network_mode: host`
  in `docker-compose.yml` (Linux only) or attach the container to the
  right user-defined network.