wbxcallprov/docker/remote-agent/deploy/README.md

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

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:

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 wbxStoreProvision

Upgrading

When you receive a newer ZIP:

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