Browse documentation

Updating the Site Collector

↩ Getting Started

A running Site Collector does not update itself. It keeps the image it was installed with until you replace its container. Some features need a newer collector — Showing guest IP addresses, for example, needs 0.13.0 or later.

Do you need to update?

Go to Settings → Site Collectors. Each collector shows the version it's running, and an Update available → v… badge when a newer one exists.

Restarting is not updating. docker restart, or rebooting the host, starts the same image again. The container has to be recreated from a freshly pulled image — which is what the steps below do.

Before you start

Shell access to the Linux host the collector runs on, with permission to run docker.
The collector's token. The installer needs it again. You can read it from the running container (Option A). If you can't, an administrator can issue a new one (Option B).
A few minutes where the collector is offline. Monitoring for its sites pauses while the container is replaced and resumes on its first heartbeat.

Step 1 — Download a fresh installer

Go to Settings → Downloads.
On the Site Collector card, select Download installer (Linux/macOS).
Copy site-collector-installer.sh to the collector host.

Use a fresh download rather than an old copy — the installer itself occasionally changes (for example, the container flags it sets).

Re-running the installer is the update: it pulls the newest collector image, removes the existing joatos-site-collector container, and starts a new one with your token.

Step 2 — Run it with the collector's token

Option A — Keep the existing token (recommended)

The token is stored in the running container's settings. Read it into a variable and pass it to the installer. The if stops the update if no token was found, so a mistake can't replace a working collector with one that can't connect:

TOKEN=$(docker inspect joatos-site-collector \
  --format '{{range .Config.Env}}{{println .}}{{end}}' | sed -n 's/^AGENT_TOKEN=//p')

if [ -n "$TOKEN" ]; then
  bash site-collector-installer.sh "$TOKEN"
else
  echo "No token found on joatos-site-collector — nothing was changed. Check the container name (docker ps -a)."
fi
unset TOKEN

The token is never printed. If it reports No token found, nothing was changed — your container most likely has a different name. See Older installs named joatos-site-collector below.

⚠ Don't delete the container before you have the token. JOATOS stores only a hash of it, so once the container is gone the token can't be recovered — only replaced (Option B).

Option B — Issue a new token

Use this if the container is already gone, or you can't read its token.

An administrator goes to Settings → Site Collectors and selects Rotate token on that collector.
Copy the new token — it's shown only once.
On the collector host, run:

bash site-collector-installer.sh <new-token>

Rotating takes effect immediately: the old token stops working the moment it's rotated, so the running collector goes offline until you run the installer with the new one. Rotate only when you're at the collector host, ready to run the installer straight away.

Step 3 — Check it's back

On the host, confirm the container is running the new image:

docker ps --filter name=joatos-site-collector --format '{{.Names}}\t{{.Image}}\t{{.Status}}'
docker logs --tail 20 joatos-site-collector

In Settings → Site Collectors, within a minute the collector should show the new version, a recent Last seen, and no Update available badge.

If Last seen doesn't move after a couple of minutes, the collector isn't authenticating — most likely the token passed in wasn't the right one. Use Option B.

Older installs named joatos-site-collector

Collectors installed before the product was renamed may run in a container called joatos-site-collector. Check with:

docker ps -a --format '{{.Names}}\t{{.Image}}' | grep -i collector

If yours is joatos-site-collector:

Run Option A with joatos-site-collector in place of joatos-site-collector in the docker inspect line. The installer creates the new joatos-site-collector container.
Once the new collector shows as online in Settings → Site Collectors, remove the old one so two containers aren't running with the same token:
```
docker rm -f joatos-site-collector
```

If you changed the collector's settings

The installer sets only API_URL and AGENT_TOKEN. If you started the container with other options yourself — such as LOG_LEVEL or POLL_INTERVAL (see Installing the Site Collector § Configuration reference) — they are not carried over. Note them before updating and recreate the container with them afterwards.

Notes & tips

The collector image is public, so no registry login is needed on the host.
Updating doesn't change which sites the collector serves or anything configured in JOATOS — that all lives on the JOATOS side.
One update brings a collector straight to the newest version; there's no need to step through versions in between.

PreviousSetting up your organization NextDocumentation