StackScout

StackScout periodically inspects Docker workloads and reports if container images have newer versions available in their source registries (initial focus: Docker Hub). If the connected Docker host is part of an active Swarm, StackScout lists Swarm services; otherwise it lists running standalone containers.

The process runs continuously: it performs an immediate scan on startup and then repeats every STACKSCOUT_POLL_INTERVAL until it receives a SIGINT/SIGTERM (e.g. container stop). This makes it suitable for running as a long‑lived service/sidecar.

Docker Image

An official container image is published to GitHub Container Registry (GHCR) on every push to the main branch.

Image reference:

ghcr.io/itsecholot/stackscout:latest

Additional immutable tags use the short commit SHA (e.g. ghcr.io/itsecholot/stackscout:abc1234).

Report (InfluxDB Payload)

For each workload (container / stack task) StackScout writes one InfluxDB point.

Tags:

• service – workload name (Swarm service or container)
• image – image repository/name (without tag changes)
• current_tag – currently deployed tag
• latest_tags – comma-separated upgrade candidates (ascending by version segment length; last is most specific)

Fields:

• update_available – boolean indicating whether at least one newer candidate exists

Timestamp: point time uses the report's generation time.

Configuration

StackScout is configured entirely via environment variables.

Variable	Type	Purpose	Default
STACKSCOUT_POLL_INTERVAL	duration	How often to perform a scan (e.g. 30m, 6h, 1h15m). Must parse with Go time.ParseDuration.	6h
STACKSCOUT_DOCKER_HOST	string	Docker host/daemon to query. Supports socket or TCP.	unix:///var/run/docker.sock
STACKSCOUT_EXCLUDE_SERVICES	string (comma list)	Names of Swarm services or standalone containers to skip.	(empty)
STACKSCOUT_INFLUX_URL	string	Base URL of InfluxDB v2 server.	http://localhost:8086
STACKSCOUT_INFLUX_TOKEN	string	InfluxDB API token (can be empty if auth disabled).	(empty)
STACKSCOUT_INFLUX_ORG	string	InfluxDB organization name.	default
STACKSCOUT_INFLUX_BUCKET	string	InfluxDB bucket to write points into.	stackscout
STACKSCOUT_INFLUX_MEASUREMENT	string	Measurement name for points (series).	stackscout

Example (Docker Compose)

services:
  stackscout:
    image: ghcr.io/itsecholot/stackscout:latest
    environment:
      STACKSCOUT_POLL_INTERVAL: 1h
      STACKSCOUT_INFLUX_URL: http://influxdb:8086
      STACKSCOUT_INFLUX_TOKEN: ${INFLUX_TOKEN}
      STACKSCOUT_INFLUX_ORG: myorg
      STACKSCOUT_INFLUX_BUCKET: metrics
      STACKSCOUT_EXCLUDE_SERVICES: traefik,helper
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro

Example via Docker

docker run --rm \
  -e STACKSCOUT_POLL_INTERVAL=1h \
  -e STACKSCOUT_INFLUX_URL=http://influxdb:8086 \
  -e STACKSCOUT_INFLUX_TOKEN=your_token \
  -e STACKSCOUT_INFLUX_ORG=myorg \
  -e STACKSCOUT_INFLUX_BUCKET=metrics \
  -e STACKSCOUT_EXCLUDE_SERVICES=traefik,helper \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  ghcr.io/itsecholot/stackscout:latest

Development Environment (Devcontainer)

All development occurs inside a VS Code devcontainer. The container includes Go, Docker CLI (via host socket mount), and common tooling.

Opening

Open the folder in VS Code; with Remote Containers / Dev Containers extension installed it will build automatically.

Post Create

Dependencies are downloaded and the project builds: go mod download && go build ./....

Building & Running

Use Makefile targets:

make build
make run
make test

Code Structure

cmd/stackscout/main.go      # entrypoint
internal/docker             # workload discovery (auto-detect swarm services vs containers)
internal/registry           # (stub) registry querying logic
internal/version            # semver comparison helpers
internal/config             # config loading & defaults
internal/report             # report data structures