Grafana dashboards as code for a homelab: version-controlled JSON dashboards and alert rules for Docker hosts and their logs, the Plex/arr media stack, reverse proxy traffic, DNS, the network and internet connection, NAS storage, UPS power, the smart home, GitLab CI, Steerhouse (an Ansible web UI), Tdarr, Plex's current streams (through Tautulli) and the Proxmox VE cluster — edited in VS Code, provisioned automatically, and shipped as Docker images with a one-container agent for each host.
Operator tools: guided setup, published-image upgrades and status snapshots. Optional integrations: authenticated TLS push endpoints, notification channels, external heartbeat, and local model servers.
Grafana, Prometheus, blackbox_exporter, pihole-exporter and unpoller (UniFi)
always run on the main server from docker-compose.yml.
Loki and the SNMP, media, Tdarr, Varken, GitLab CI and Proxmox exporters are
optional Compose profile services; Loki can run on another host. Exporters
beside Plex or GPUs and the hardware exporters run on the monitored hosts,
not in the main server stack. An Argus agent on each monitored Docker host or
Kubernetes node pushes its metrics and logs to the server. Grafana loads
every dashboard under dashboards/ through file provisioning —
each subfolder becomes a Grafana folder, and UI edits are blocked so this repo
stays the source of truth. The same compose file runs production and a local
sandbox; per-install settings come from a gitignored .env, while targets
and credentials stay in gitignored targets/ and secrets/ directories.
dashboards/ dashboard JSON, one folder per Grafana folder
provisioning/ Grafana datasources (pinned uids), dashboard provider
and alert rules
prometheus/ Prometheus config — scrape jobs, no addresses
blackbox/ blackbox_exporter probe modules (HTTP service check, DNS
resolve)
agent/ the Argus agent image (Grafana Alloy + config) and its
compose file, one per monitored host
logs/ Loki config, plus a compose file to run Loki on a separate
host with more disk
images/ Dockerfiles for the published server images
targets.example/ placeholder scrape/probe targets; real ones go in targets/
(gitignored)
secrets.example/ placeholder credentials Prometheus scrapes with; real ones
go in secrets/ (gitignored)
deploy/ host exporter setup scripts and deployment units
snmp/ custom SNMP module for Synology SSD caches
scripts/ repo checks, PromQL test builder, Intel GPU exporter,
deployment helper and Steerhouse dashboard port
tests/ unit tests (pytest) and PromQL tests (tests/promql/, run
with promtool)
docs/ setup, operations, architecture, security and project
documentation
-
Dashboard: Homelab Overview (home page)
- Folder: overview
- Answers: Is everything up right now, and if not, what?
- Data: Uptime Kuma
/metrics, blackbox_exporter HTTP + DNS probes
-
Dashboard: DNS / Pi-hole
- Folder: dns
- Answers: Is DNS healthy and consistent, and what's being blocked?
- Data: pihole-exporter (Pi-hole v6 API), blackbox DNS probes
-
Dashboard: Host Health
- Folder: hosts
- Answers: Is any machine running out of disk, memory or CPU?
- Data: Argus agent on each host (embedded node_exporter)
-
Dashboard: GPUs
- Folder: hosts
- Answers: Are the GPUs doing the transcoding, and are they healthy?
- Data:
nvidia_gpu_exporter
(nvidia-smi) beside the agent on a GPU host (
agent/compose.yml,gpuprofile); Intel GPUs from Argus' Intel GPU exporter (intel_gpu_top, see docs/intel-gpu.md) with temperature and power from hwmon
-
Dashboard: Local Model Servers
- Folder: hosts
- Answers: Which models are loaded, and are requests or KV cache saturated?
- Data: vLLM's native
/metricsendpoint; see docs/local-models.md
-
Dashboard: Databases
- Folder: hosts
- Answers: Are the shared database servers up, and is any app close to running out of connections, cache or room?
- Data: postgres_exporter and mysqld_exporter, running beside PostgreSQL and MariaDB
-
Dashboard: Docker Containers
- Folder: hosts
- Answers: Which containers are restarting, stopped, or eating resources?
- Data: Argus agent on each host (embedded cAdvisor)
-
Dashboard: Network / UniFi
- Folder: network
- Answers: How's the internet connection, and what's on the network?
- Data: unpoller with a read-only UniFi account
-
Dashboard: Internet / ISP
- Folder: network
- Answers: Is the ISP delivering the speed we pay for, and how often does the connection drop?
- Data: unpoller: the UniFi gateway's own speed tests and the plan speeds set in UniFi
-
Dashboard: Media Stack
- Folder: media
- Answers: Who's watching what, is the download pipeline flowing, and is the library healthy?
- Data: exportarr (*arr, SABnzbd),
qbittorrent-exporter;
Plex exporter beside Plex (
agent/compose.yml,plexprofile)
-
Dashboard: Tautulli
- Folder: media
- Answers: What's playing on Plex right now, and how is it being delivered?
- Data: Varken's Prometheus
output, reading Tautulli's API (
varkenprofile): streams, transcode decisions, bandwidth, sessions by quality and platform, library sizes
-
Dashboard: Varken
- Folder: media
- Answers: What's on Plex, who's watching from where, and what are Sonarr, Radarr and Seerr waiting on?
- Data: The original
Varken
dashboard,
ported to Prometheus, with Seerr in place of Ombi and without SickChill:
Varken 3.0's metrics with
stream_detailson (viewer names, titles and cities) and GeoIP on (a MaxMind account:maxmind_license_keysecret, account ID invarken.env) for the map; Sonarr and Radarr (and their 4K instances, with an HD/4K column) and Seerr's requests and issues through Varken too
-
Dashboard: Varken [Classic]
- Folder: media
- Answers: The same, in the original Varken dashboard's look
- Data: The Varken dashboard's queries, restyled like the original "Varken [Official]" (coloured tiles and rows, heat strip, US map)
-
Dashboard: Tdarr
- Folder: media
- Answers: Is Tdarr keeping up, and how much space has it saved?
- Data: tdarr-exporter
through Tdarr's API (
tdarrprofile); the Tdarr container's CPU, memory and logs from the Argus agent
-
Dashboard: NAS / Storage
- Folder: storage
- Answers: Are the NAS units healthy, and how fast are they filling?
- Data: snmp-exporter (bundled
synology+ standard MIB modules, and Argus'synology_flashcachefor SSD caches), SNMPv3
-
Dashboard: Smart Home
- Folder: home
- Answers: What's the house doing — temperatures, HVAC, energy?
- Data: Home Assistant's Prometheus integration (long-lived token)
-
Dashboard: Reverse Proxy Traffic
- Folder: network
- Answers: What's hitting the services behind the reverse proxy, and is anything erroring?
- Data: Nginx Proxy Manager access logs → Alloy → Loki
-
Dashboard: Logs
- Folder: hosts
- Answers: What did a host or container log around the time something broke?
- Data: Docker container logs → Alloy → Loki
-
Dashboard: Deploys
- Folder: ci
- Answers: Did every merge reach its host, and is every host's deploy agent alive?
- Data: homelab-pull's metrics and
deploy log (a pull-based deploy agent: one stack per host, deployed from its
git branch), read by the Argus agent (
HOMELAB_PULL_DIR); deploy markers on Host Health and Docker Containers
-
Dashboard: GitLab CI
- Folder: ci
- Answers: Are pipelines healthy, are the runners keeping up, and is GitLab itself healthy?
- Data:
gitlab-ci-pipelines-exporter
with a
read_apitoken (gitlabprofile); GitLab Runner's metrics endpoint; a subset of GitLab's bundled Prometheus (Omnibus), read through/federate
-
Dashboard: Steerhouse: overview & runs
- Folder: ci
- Answers: Is Steerhouse healthy right now, and how have its Ansible runs gone: which failed, and how long did they take?
- Data: Steerhouse's
token-protected
/metrics(port 8002) and its database's read-onlyanalyticsviews, as thegrafana_rorole over TLS; the three Steerhouse dashboards are Steerhouse's own, ported byscripts/port_steerhouse.py
-
Dashboard: Steerhouse: execution, queue & workers
- Folder: ci
- Answers: Is Steerhouse keeping up: are runs waiting for a worker, are notifications going out, and is its API healthy?
- Data: The same
-
Dashboard: Steerhouse: security & access
- Folder: ci
- Answers: Is anyone trying to get into Steerhouse, and who changed users, access or keys?
- Data: The same
-
Dashboard: Proxmox VE
- Folder: proxmox
- Answers: Are the Proxmox nodes overcommitted, are the guests that should run running, and how is storage filling?
- Data:
prometheus-pve-exporter
with a read-only API token (
proxmoxprofile)
-
Dashboard: Server Hardware
- Folder: proxmox
- Answers: Is the server hardware healthy: temperatures, fans, power supplies, batteries, power draw, room in the BMCs' event logs, and add-in GPUs, including how busy an Intel GPU is?
- Data:
prometheus-ipmi-exporter
on each server (Debian package), reading its own BMC through
/dev/ipmi0— see docs/ipmi.md; add-in GPUs, which the BMC can't see, from node_exporter's hwmon collector (Debian package, hwmon only) — see docs/hwmon.md; Intel GPU load from Argus' own exporter aroundintel_gpu_top— see docs/intel-gpu.md
-
Dashboard: UPS / Power
- Folder: power
- Answers: How long would the lab survive a power cut, and is the UPS healthy?
- Data: PeaNUT
/api/v1/metrics
Grafana-managed alert rules live in
provisioning/alerting/rules.yaml (edit
there — UI changes are blocked) and notify a Discord channel through the webhook
in secrets/discord_webhook_url (its template points nowhere, so a sandbox
can't post). Optional e-mail, Slack and ntfy channels
can replace Discord. Each rule is a raw PromQL or LogQL measurement (A) plus a
threshold (C),
one alert per series:
-
Group: Availability
- Rules: host stopped reporting (its agent went silent), service down (only services that were up for at least an hour in the last 7 days), DNS server not answering, monitoring target down (not a host's NVIDIA or Intel GPU exporter while that host says it's on another GPU), Proxmox node without cluster quorum, Proxmox QDevice disconnected for 5 minutes, GPU exporter reporting no GPU (driver not loaded), an Intel GPU on its server's driver that intel_gpu_top can't read for 10 minutes
-
Group: Capacity
- Rules: local disk > 90 % (network shares are covered by the NAS pool rule), NAS storage pool > 90 %, certificate < 14 days, Proxmox node memory > 90 % used, Proxmox node memory overcommitted (running guests allocated > 100 %)
-
Group: Power and hardware
- Rules: UPS on battery, UPS battery < 50 %, NAS disk unhealthy, NAS pool degraded, NAS disk > 55 °C, network device > 85 °C, GPU > 85 °C (NVIDIA, and Intel cards read by the server's driver), a BMC sensor critical for 5 minutes (a failed battery, power supply or fan, or a reading past its critical limit; empty slots and Supermicro's LED pattern sensors don't count), a BMC sensor in warning for 15 minutes, a BMC that can't be read for 10 minutes, a BMC event log with < 1 KiB left
-
Group: Network
- Rules: internet on backup WAN, internet dropped, internet much slower than usual (latest speed test under half its 14-day median), no speed test in 8 days, Pi-hole blocklists out of sync
-
Group: Containers
- Rules: container restarted more than 3 times in an hour
-
Group: Logs
- Rules: a site returning > 20 server errors (5xx) in 10 minutes, log pipeline stalled (Loki receiving almost nothing for 15 minutes)
-
Group: Tautulli
- Rules: Varken can't read Tautulli for 10 minutes (down, wrong API key or an unreadable reply), Tautulli data stale for 10 minutes while Varken still reports it up (a hanging request)
-
Group: Tdarr
- Rules: new transcode or health-check errors in the last hour, files queued but no transcode or health check finished in a day
-
Group: Deploys
- Rules: a deploy agent that hasn't finished a run for 50 minutes, a deploy failing for 15 minutes, every run of an agent failing for 15 minutes (fetch or settings), deploys paused for 2 hours (the checkout isn't on its branch)
-
Group: GitLab
- Rules: a GitLab component (Puma, Sidekiq, Gitaly, PostgreSQL, …) down for 5 minutes, the latest pipeline on a watched branch failed
-
Group: Steerhouse
- Rules: more than 30 % of the runs that ended in the last hour failed or timed out (for 15 minutes), over 30 failed sign-ins in 15 minutes, a notification waiting over 15 minutes to be sent, Steerhouse's API unable to read its database for 5 minutes. Single events (a failed run, a worker offline, a lockout) are Steerhouse's own notifications; its metrics not arriving is "monitoring target down"
Alerts are grouped per rule and repeat every 12 hours while firing.
Requirements: Linux with Docker Compose v2.24 or later, Git and OpenSSL for the setup below, on amd64 or arm64. One host runs the server; monitored Docker hosts and Kubernetes nodes run the agent using their respective guides.
Five Argus images (Grafana, Prometheus, blackbox, Loki and agent) support amd64
and arm64; the Intel GPU exporter image supports amd64 only. Images ship on GHCR
(ghcr.io/honeybeartech/argus-*) and Docker Hub (honeybeartech/argus-*; set
ARGUS_REGISTRY=docker.io/honeybeartech in .env to use it). The Grafana image
has every dashboard, datasource and alert rule baked in; the Prometheus,
blackbox and Loki images carry their configs. What stays on the host is what's
specific to your network: scrape targets, credentials and .env.
Server (one host — Grafana, Prometheus, blackbox_exporter, Loki):
git clone --depth 1 https://github.com/HoneyBearTech/Argus.git && cd Argus
chmod 700 . # keep the checkout private on the host
cp .env.example .env # set GRAFANA_ROOT_URL
mkdir -p targets secrets && cp targets.example/*.json targets/ && cp \
secrets.example/* secrets/
# Required Grafana admin password; generate without printing it
(umask 077 && openssl rand -base64 24 > secrets/grafana_admin_password)
chmod 644 secrets/grafana_admin_password # readable by Grafana's container user
# set local-trial binds in .env as described below before starting
# put your real addresses in targets/ and credentials in secrets/
# keep required mounted credential templates, even for unused integrations
docker compose up -dKeep CONFIG_ROOT from the copied .env.example defined: Compose requires
it when parsing even if varken is disabled. When enabling varken, prepare
CONFIG_ROOT/varken/config as its persistent data directory, owned by uid 1000.
Keep the checkout directory private on the host; mounted credential files need mode 644 so the containers can read them. See the quick start for details.
For a local trial, set GRAFANA_BIND, PROMETHEUS_BIND and LOKI_BIND in
.env to 127.0.0.1:3000, 127.0.0.1:9090 and 127.0.0.1:3101 before
starting the server. This keeps the services reachable only from the server
itself. For agents on other hosts, configure binds and network access
deliberately as described in security requirements.
Then run the agent on each host you want to watch (next section). Grafana is on
port 3000; the home page is the Homelab Overview. Edits to targets/*.json are
picked up by Prometheus without a restart.
Host Health, Docker Containers and Logs work with just the agents. Every other
dashboard lights up as you connect the service it reads. COMPOSE_PROFILES
starts as loki: add profiles to that list (loki,snmp) rather than replacing
it, or Loki stops (unless it runs on another host, with LOKI_URL set):
-
To see: Service up/down, certificates (Overview)
- Add to
targets/:blackbox_http.json(URLs),blackbox_dns.json(DNS servers) - Credentials in
secrets/: — - Add to
COMPOSE_PROFILESin.env: —
- Add to
-
To see: Uptime Kuma monitors (Overview)
- Add to
targets/:uptime_kuma.json - Credentials in
secrets/:uptime_kuma_api_key - Add to
COMPOSE_PROFILESin.env: —
- Add to
-
To see: DNS / Pi-hole
- Add to
targets/:blackbox_dns.json - Credentials in
secrets/:pihole-exporter.env - Add to
COMPOSE_PROFILESin.env: —
- Add to
-
To see: Network / UniFi, Internet / ISP
- Add to
targets/: — - Credentials in
secrets/:unpoller.env(console URL + read-only local account),unifi_password - Add to
COMPOSE_PROFILESin.env: —
- Add to
-
To see: NAS / Storage
- Add to
targets/:snmp.json(addsynology_flashcacheto a Synology'smodulelist for its SSD cache) - Credentials in
secrets/:snmp-auth.yml(SNMPv3) - Add to
COMPOSE_PROFILESin.env:snmp
- Add to
-
To see: Smart Home
- Add to
targets/:homeassistant.json - Credentials in
secrets/:home_assistant_token - Add to
COMPOSE_PROFILESin.env: —
- Add to
-
To see: UPS / Power
- Add to
targets/:peanut.json - Credentials in
secrets/:peanut_username,peanut_password(PeaNUT 6's login; PeaNUT 5 ignores them) - Add to
COMPOSE_PROFILESin.env: —
- Add to
-
To see: Media Stack (*arr, SABnzbd, qBittorrent)
- Add to
targets/:media.json(enabled exporters only) - Credentials in
secrets/:<app>.env(URL),<app>_api_key(qBittorrent:qbittorrent.envwith URL + user,qbittorrent_password) - Add to
COMPOSE_PROFILESin.env: the app's profile, e.g.radarr,sonarr
- Add to
-
To see: Tautulli
- Add to
targets/:varken.json(varken:9180) - Credentials in
secrets/:varken.env(Tautulli's, Sonarr's, Radarr's, Lidarr's and Seerr's addresses, SSL settings),tautulli_api_keyand the Sonarr/Radarr (and 4K) and Lidarr API keys exportarr uses,seerr_api_key; andCONFIG_ROOT/varken/configowned by uid 1000 - Add to
COMPOSE_PROFILESin.env:varken
- Add to
-
To see: Tdarr
- Add to
targets/:tdarr.json(tdarr-exporter:9090) - Credentials in
secrets/:tdarr.env(Tdarr's URL; andTDARR_API_KEYonce Tdarr's own login is on, which the exporter reads only from its environment) - Add to
COMPOSE_PROFILESin.env:tdarr
- Add to
-
To see: Server Hardware
- Add to
targets/:ipmi.json(<server>:9290, with ahostlabel) - Credentials in
secrets/:ipmi_password(the exporters' basic auth; set up each server withdeploy/ipmi/, see docs/ipmi.md) - Add to
COMPOSE_PROFILESin.env: —
- Add to
-
To see: Server Hardware (add-in GPUs)
- Add to
targets/:hwmon.json(<server>:9100, with the samehostlabel) - Credentials in
secrets/:hwmon_password(node_exporter's basic auth; set up each server withdeploy/hwmon/, see docs/hwmon.md) - Add to
COMPOSE_PROFILESin.env: —
- Add to
-
To see: Server Hardware (Intel GPU load)
- Add to
targets/:intel_gpu.json(<server or host>:9836, with ahostlabel) - Credentials in
secrets/:intel_gpu_password(the Intel GPU exporters' basic auth; set up a server withdeploy/intelgpu/, see docs/intel-gpu.md) - Add to
COMPOSE_PROFILESin.env:intel-gpu, on a host or VM with the agent, withARGUS_INTEL_GPU_PASSWORD_HASH
- Add to
-
To see: GPUs
- Add to
targets/:gpu.json(<gpu host>:9835, with ahostlabel) - Credentials in
secrets/: — - Add to
COMPOSE_PROFILESin.env:gpu, in that host's agent.env(needs the NVIDIA Container Toolkit)
- Add to
-
To see: Media Stack (Plex)
- Add to
targets/:plex.json - Credentials in
secrets/:PLEX_TOKENin the Plex host's agent.env - Add to
COMPOSE_PROFILESin.env:plex, in that host's agent.env
- Add to
-
To see: Loki's own health
- Add to
targets/:loki.json(loki:3100for the bundled one) - Credentials in
secrets/: — - Add to
COMPOSE_PROFILESin.env: —
- Add to
-
To see: GitLab CI (pipelines)
- Add to
targets/:gitlab.json - Credentials in
secrets/:gitlab.yml(GitLab's URL and aread_apitoken) - Add to
COMPOSE_PROFILESin.env:gitlab
- Add to
-
To see: GitLab CI (runners)
- Add to
targets/:gitlab_runner.json(<runner>:9252, one target per runner); setlisten_address = ":9252"in each runner'sconfig.toml - Credentials in
secrets/: — - Add to
COMPOSE_PROFILESin.env: —
- Add to
-
To see: GitLab CI (GitLab's health)
- Add to
targets/:gitlab_server.json(<gitlab>:9090); setprometheus['listen_address'] = '0.0.0.0:9090'ingitlab.rband rungitlab-ctl reconfigure(restarts Puma and Sidekiq: a minute or two of 502s) - Credentials in
secrets/: — - Add to
COMPOSE_PROFILESin.env: —
- Add to
-
To see: Steerhouse
- Add to
targets/:steerhouse.json(<steerhouse host>:8002, the backend's metrics port, which Steerhouse serves onceMETRICS_TOKENandMETRICS_HOSTare set); andSTEERHOUSE_DB_ADDRESSin.env(its PostgreSQL,host:port) - Credentials in
secrets/:steerhouse_metrics_token(Steerhouse'sMETRICS_TOKEN),steerhouse_db_password(thegrafana_rorole's password: see docs/steerhouse.md),steerhouse_db_ca(the CA certificate that signed the database's TLS certificate, which must name the address) - Add to
COMPOSE_PROFILESin.env: —
- Add to
-
To see: Databases
- Add to
targets/:postgres.json(<db server>:9187) andmysql.json(<db server>:9104), each target with ahostlabel - Credentials in
secrets/: — (the exporters keep their own database logins) - Add to
COMPOSE_PROFILESin.env: —
- Add to
-
To see: Proxmox VE
- Add to
targets/:pve.json: each node's API address (port 8006 by default), which the node's certificate must name; in a cluster, label every node but one"cluster": "0" - Credentials in
secrets/:pve.yml(an API token with thePVEAuditorrole; the commands are in the template),pve-ca.pem(the cluster's CA,/etc/pve/pve-root-ca.pemon any node) - Add to
COMPOSE_PROFILESin.env:proxmox
- Add to
To upgrade, pull new images (docker compose pull && docker compose up -d), or
pin ARGUS_VERSION in .env to a release; see
docs/upgrading.md. New to Argus? The
quick start runs it on one machine in about ten minutes.
Security: Prometheus (9090) and Loki (3101) accept pushes without
authentication, so agents anywhere on the network can reach them; Prometheus can
require a password. Run
Argus on a trusted network, and put Grafana behind a reverse proxy with TLS if
it's reachable from outside (docker-compose.proxy.yml puts Grafana on the
network of a proxy running in Docker on the same host, so its own port can
listen on loopback only). What Argus does and doesn't protect against is in
docs/security.md.
Developing — to edit dashboards, alert rules or configs live, run from the
checkout instead of the published images by setting
COMPOSE_FILE=docker-compose.yml:docker-compose.source.yml in .env. Grafana
then reads dashboards/ and provisioning/ straight from the repo (dashboard
edits show up within 30 seconds), and docker compose up -d --build rebuilds
the images. In this mode, deploying is git pull on the server; restart the
stack only when docker-compose.yml, provisioning/ or a config changes. A
systemd timer can do that for you once CI passes: see
docs/auto-deploy.md.
Releases are published by pushing a signed v*.*.* tag
(.github/workflows/release.yml): the images
are signed with cosign and carry an SBOM and provenance, and the GitHub Release
gets its notes from CHANGELOG.md and a signed checksum file.
docs/verifying-releases.md shows how to check
them.
Set the required ARGUS_HOST, ARGUS_PROMETHEUS_URL and ARGUS_LOKI_URL
for every agent. The Docker-host setup below collects Docker metrics and logs;
Kubernetes nodes use the same image with node-specific
configuration and a DaemonSet.
Each monitored host runs one container, the Argus agent (agent/): Grafana
Alloy with embedded node_exporter and cAdvisor that pushes host metrics,
container metrics and container logs to the Argus server. Nothing on the server
needs to change — the host appears in the dashboards as soon as the agent
starts, and it only makes outbound connections (no firewall rules on the host).
docker run -d --name argus-agent --restart unless-stopped \
--network host --pid host --read-only \
--cap-drop ALL --cap-add DAC_OVERRIDE --security-opt no-new-privileges:true \
-e ARGUS_HOST=my-host \
-e ARGUS_PROMETHEUS_URL=http://argus-server:9090 \
-e ARGUS_LOKI_URL=http://argus-server:3101 \
-v /:/rootfs:ro,rslave -v /sys:/sys:ro -v /run/udev:/run/udev:ro -v \
/dev/disk:/dev/disk:ro \
-v /var/lib/docker:/var/lib/docker:ro -v \
/var/run/docker.sock:/var/run/docker.sock:ro \
-v /run/containerd:/run/containerd:ro -v \
argus-agent-data:/var/lib/alloy/data \
ghcr.io/honeybeartech/argus-agent:0.9.0It runs as root in the host's network and PID namespaces with the host mounted
read-only, but not privileged: its only capability is DAC_OVERRIDE (to read
files that belong to other users), and its own filesystem is read-only, so it
writes only its data volume. Why it needs each of these is in
docs/security.md.
Or copy agent/compose.yml and agent/.env.example (as .env) to the host and
run docker compose up -d; pin ARGUS_AGENT_IMAGE to a release tag for
predictable upgrades. The compose file also covers five extras:
- Nginx Proxy Manager access logs (Reverse Proxy Traffic dashboard): on the
host running NPM, set
NPM_LOG_DIRto itsdata/logsdirectory. - homelab-pull deploys (Deploys dashboard): on a host whose Docker Compose
stack homelab-pull (0.4.0 or later) deploys, set
HOMELAB_PULL_DIRto its state directory (~/.local/state/homelab-pullof the user it runs as). The agent reads its metrics files (metrics/*.prom, node_exporter's textfile collector) and each stack'sdeploys.log. - NVIDIA GPUs (GPUs dashboard): on a host with an NVIDIA GPU, the NVIDIA
Container Toolkit 1.18 or later and Docker Engine 29.2 or later, add the
gpuprofile, and list that host in the server'stargets/gpu.json. From 29.2, Docker serves the exporter'sdriver: nvidiareservation through CDI (the toolkit'snvidia-cdi-hook, withnvidia-cdi-refreshkeeping the CDI spec current). An older Engine uses NVIDIA's runtime hook, and the container loses the GPU at everysystemctl daemon-reload(apt and unattended-upgrades run one):nvidia-smifails with "Failed to initialize NVML: Unknown Error" (NVIDIA container-toolkit issue #48) and the "GPU not reporting" alert fires. To check a host:sudo systemctl daemon-reload, thendocker exec argus-gpu-exporter nvidia-smi -Lstill lists the GPU. A host whose GPU can change (a VM that fails over to a machine with an Intel GPU and stops its exporter there) can say which GPU it booted with,homelab_gpu_selected{vendor="intel"} 1, so its stopped exporter doesn't raise "Monitoring target down" (docs/interfaces.md). - Intel GPUs (Server Hardware dashboard): on a host or VM whose own i915
driver has an Intel GPU (amd64), add the
intel-gpuprofile withARGUS_INTEL_GPU_PASSWORD_HASH, and list that host in the server'stargets/intel_gpu.json. The exporter's only privilege isPERFMON(docs/intel-gpu.md). A host whose GPU can change switches it on only while it has the Intel GPU; withhomelab_gpu_selectedit doesn't alert while it's off. - Plex (Media Stack): on the Plex host (amd64), add the
plexprofile withPLEX_SERVERandPLEX_TOKEN, and list that host in the server'stargets/plex.json.
Kubernetes nodes run the same image as a DaemonSet with its second
configuration, kubernetes.alloy: node metrics, container metrics from each
node's kubelet and pod logs, under the same labels, with no container runtime
socket (docs/kubernetes.md).
The agent needs the server's Prometheus (9090) and Loki (3101) to be reachable
from the host; those are the defaults. If Prometheus requires a password, add
-e ARGUS_PROMETHEUS_PASSWORD=... (or set it in the agent's .env).
- Build or edit it in the sandbox Grafana, then Export → Export as JSON (leave "Export for sharing externally" off), or edit the JSON directly in VS Code.
- Save it under
dashboards/<folder>/<name>.jsonwith a stable, hand-pickeduid,"id": null, theargustag, and a description saying what question it answers. - Reference datasources by uid (
prometheus) — never by name or URL. - Run
python3 scripts/check_dashboards.py. It also fails on private IP addresses and on internal names listed one regex per line in a gitignored.forbidden-patternsfile (CI reads the same list from theARGUS_FORBIDDEN_PATTERNSsecret): this repo is public, so addresses stay intargets/and.env.
CI (.github/workflows/ci.yml) runs on every push
and pull request: linters for Python, YAML, workflows, Dockerfiles and the agent
config; unit tests with a coverage floor; the dashboard and public-repo checks;
promtool check config and the PromQL tests, which run the
shipped alert rule and dashboard queries against synthetic series; the blackbox,
Loki and Alloy config checks; it builds every image, starts Grafana to check
that every dashboard, alert rule and datasource loads, and validates the compose
files.
Alongside it: CodeQL analyses the Python checks
and the workflows on every push and pull request and weekly, a weekly
Trivy scan reports known vulnerabilities in the six
images, OpenSSF Scorecard scores the repo's
supply-chain practices weekly (see the badge above). When its integration is
enabled, Renovate follows renovate.json: weekly dependency
PRs and grouped minor and patch updates. Renovate merges every update, majors
included, by itself once every check on the pull request has passed and the new
version is 3 days old. How dependencies are handled is in
docs/dependencies.md.
Check service status and recent server logs without changing the deployment:
docker compose ps
docker compose logs --tail=100 grafana prometheus blackbox pihole-exporter unpollerCheck Grafana's /api/health on its configured port 3000 bind and Prometheus'
/-/ready on its configured port 9090 bind; Prometheus requires authentication
when enabled. Use its Targets page to inspect scrape errors. If startup fails,
check .env, required mounted credential files and container read permissions
before retrying; see the quick start.
For routine maintenance, see upgrading, release verification and security requirements. For deployment setup, see auto-deploy; for a service or port lookup, use interfaces.
docs/ has the quick start, architecture, interfaces, upgrading, security requirements and assurance case, dependency policy and roadmap. Changes are listed in CHANGELOG.md.
Bug reports and ideas go in GitHub Issues; see CONTRIBUTING.md for the development setup, coding standards, test policy and sign-off, SECURITY.md for reporting vulnerabilities privately, and SUPPORT.md for which versions are supported. The project's governance and code of conduct apply to everyone taking part.