Skip to content

Deploy — upgrade the Argus stack

Runbook to promote an Argus version on a Docker host. Applies when you use images published on GHCR or build locally from a clone.

Available versions: GitHub Releases · images ghcr.io/harryraddatz/argus-{hub,agent,web} and docker.io/pseudohuery/argus-{hub,agent,web} (same content, linux/amd64 and linux/arm64).

Before you upgrade

  1. Read the version section in CHANGELOG.md. On a major change, look for Breaking and adjust .env before you start.
  2. Confirm .env has any new variables listed in .env.example.
  3. The hub stores data in the Postgres database named by ARGUS_STORE_DSN. docker compose down does not delete that database. Take a database dump with your own Postgres tools before a major upgrade.

Option A — published images (GHCR)

Pin the version with ARGUS_VERSION (no v prefix). Without it, compose uses latest. To pull from Docker Hub instead of GHCR, set ARGUS_REGISTRY=docker.io/pseudohuery.

export ARGUS_VERSION=0.1.1
# export ARGUS_REGISTRY=docker.io/pseudohuery
docker compose -f examples/compose-minimal/docker-compose.published.yml pull
docker compose -f examples/compose-minimal/docker-compose.published.yml up -d --force-recreate

For a custom compose file, set image: to ghcr.io/harryraddatz/argus-<component>:${ARGUS_VERSION} and run the same commands.

Option B — local build

From the clone, on the tag you want:

git fetch --tags
git checkout v0.1.1
docker compose up -d --build --force-recreate

Why --force-recreate

docker compose restart restarts the container with the old configuration: it does not reread env_file or swap the image. After changing .env, a tag, or an image, recreate containers with up -d --force-recreate.

Post-deploy checklist

Adjust host and ports if you are not using the defaults (8080 hub, 3000 panel).

  1. Hub is up:
curl -fsS http://localhost:8080/health
# {"status":"ok"}
  1. The panel returns 200 and proxies the API:
curl -fsS -o /dev/null -w '%{http_code}\n' http://localhost:3000/
curl -fsS http://localhost:3000/health
  1. Agent is reporting (wait one ARGUS_COLLECT_INTERVAL cycle, default 15s):
curl -fsS -H "Authorization: Bearer $ARGUS_AGENT_TOKEN" 'http://localhost:8080/api/v1/workloads?since=5m' | head -c 500
curl -fsS -H "Authorization: Bearer $ARGUS_AGENT_TOKEN" http://localhost:8080/api/v1/fleet/status | head -c 500

The workload list must not be empty if containers are running on the host.

  1. Logs have no ingest authentication errors (token mismatch between hub and agent):
docker compose logs --since 5m argus-agent | grep -i -E 'error|401' || echo ok
  1. In the panel, Overview and Containers show recent data.

Rollback

Go back to the previous version and recreate:

export ARGUS_VERSION=0.1.0
docker compose -f examples/compose-minimal/docker-compose.published.yml up -d --force-recreate

For a local build: git checkout v0.1.0 && docker compose up -d --build --force-recreate.

If the new version changed the database schema, restore the dump taken before the deploy.