Skip to content

Self-hosted monitoring for homelabs: host and container metrics and uptime checks from all your machines in one dashboard, with an optional AI agent that diagnoses incidents and suggests fixes.

docs: revise README for clarity and additional details (#179)

Karlo Kajba Šimanić42d03dbc40ce
diff --git a/README.md b/README.md
index 7431362..ebd0a27 100644
--- a/README.md
+++ b/README.md
@@ -1,90 +1,117 @@
-<img width="2000" height="500" alt="infradeck-banner" src="https://github.com/user-attachments/assets/a8fcce0c-e46c-4be3-96ad-a9a16c328a29" />
+<p align="center">
+ <img width="2000" height="500" alt="Infradeck: Every server. Every container. One dashboard." src="https://github.com/user-attachments/assets/a8fcce0c-e46c-4be3-96ad-a9a16c328a29" />
+</p>
+
+<p align="center">
+ <strong>Know what's healthy. Fix what isn't.</strong><br/>
+ Self-hosted monitoring for your homelab: every server, every container and every service you run, in one dashboard.
+</p>
+
+<p align="center">
+ <a href="LICENSE"><img alt="License: AGPL-3.0" src="https://img.shields.io/badge/license-AGPL--3.0-blue"></a>
+ <img alt="Self-hosted" src="https://img.shields.io/badge/self--hosted-Docker%20Compose-2496ED">
+ <!-- After the first GitHub release, add:
+ <a href="https://github.com/karloks2005/infradeck/releases"><img alt="Latest release" src="https://img.shields.io/github/v/release/karloks2005/infradeck"></a>
+ CI badge (replace ci.yml with the real workflow file name):
+ <a href="https://github.com/karloks2005/infradeck/actions"><img alt="CI" src="https://github.com/karloks2005/infradeck/actions/workflows/ci.yml/badge.svg"></a>
+ -->
+</p>
+
+<p align="center">
+ <a href="#quick-start">Quick start</a> ·
+ <a href="#deploying-on-a-server">Deploy</a> ·
+ <a href="#features">Features</a> ·
+ <a href="#security">Security</a> ·
+ <a href="docs/README.md">Docs</a>
+</p>
+
+<!-- TODO: make this first screenshot the Overview page with several servers -->
+<img width="2879" height="1499" alt="Infradeck screenshot" src="https://github.com/user-attachments/assets/a1541d08-5cb5-4926-b553-d1512159c265" />
+
+## Why Infradeck
+
+One machine runs the dashboard. Every other machine runs a small collector that reports host and Docker metrics and runs your uptime checks. It works the same on one LAN or across sites and VPSes.
+
+- **Hosts, containers and uptime in one place.** No separate tools for server metrics, Docker and "is my service up".
+- **Checks run from your own machines.** Pick which servers run each check, so you can tell a broken service from a broken network path.
+- **Alerts that mean something.** One incident per problem, opened after a sustained breach, closed automatically when it clears.
+- **Secure by design.** Collectors never get the Docker socket, report only over your VPN, and install signed, digest-pinned images.
+- **An optional AI incident agent that only reads.** It diagnoses warning and critical incidents from masked data and proposes fixes. It never runs commands on your servers.
+- **Add a server with one command and one click.**
+
+## Quick start
+
+Try it on one machine with Docker Compose:
+
+<!-- TODO: verify these commands -->
+```bash
+git clone https://github.com/karloks2005/infradeck.git
+cd infradeck
+cp example.env .env
+docker compose up -d --build
+```
+
+1. Get the one-time **setup token** from the backend log:
+ `docker compose logs backend | grep "setup token"`
+2. Open http://localhost:5173 and register with it. The first account is the admin. Passwords need at least 16 characters (a few random words work well).
+3. This machine appears under **New servers detected**. Click **Add**. Metrics arrive within seconds.
+
+Health check: http://localhost:5173/api/health
-# Infradeck | Know What's Healthy - Fix What Isn't
+```bash
+docker compose logs -f backend frontend collector # follow logs
+docker compose --profile system-events up -d # also run the optional system helper
+docker compose down # stop (data volumes are kept)
+```
-A self-hosted dashboard for monitoring all your homelab machines in one place.
-One machine runs the dashboard; every other machine runs a small collector that
-reports host and Docker container metrics back to it, and runs the uptime checks
-you define (HTTP, TCP, TLS, DNS, ping and more). It works the same whether the
-machines share a LAN or are spread across sites and VPSes.
+To try **Connect a server** on the same machine, set `COLLECTOR_IMAGE` and `DOCKER_PROXY_IMAGE` in `.env` to `infradeck-collector:latest` and `infradeck-docker-proxy:latest` (the images Compose just built). Other machines need published images; see [Publishing the collector images](docs/deployment.md#publishing-the-collector-images).
-It also includes an optional incident agent (OpenAI API, set `OPENAI_API_KEY`): it diagnoses each
-incident from the data Infradeck already has, proposes fixes, watches whether the fix holds and adds its
-diagnosis to your notifications. It reads; it never runs commands on your servers.
+## Deploying on a server
-<img width="2879" height="1499" alt="image" src="https://github.com/user-attachments/assets/4331b563-9537-4393-882d-f0dbe5a1aedd" />
+The server stack (`docker-compose.server.yml`) publishes the dashboard through the reverse proxy you already run (a ready-made **Traefik** file is in [`deploy/`](deploy)). Collector endpoints are served only on a separate listener bound to your **VPN address**.
-Security comes first: the collectors never get the Docker socket, remote machines
-report over a VPN to a listener the public internet can't reach, and nothing
-the dashboard serves is ever executed on your hosts. See [SECURITY.md](SECURITY.md)
-for what every component can touch and the limits of each protection.
+1. `cp example.env .env`, then set `POSTGRES_PASSWORD`, `REDIS_PASSWORD`, `DASHBOARD_DOMAIN`, `TRUSTED_PROXIES` and `COMPOSE_FILE=docker-compose.server.yml` (with Traefik: `docker-compose.server.yml:deploy/traefik.yml`, plus your Traefik names).
+ > `COMPOSE_FILE` matters: without it Compose runs the development stack.
+2. Generate `SECRETS_KEY` (needed for two-factor sign-in) and set `COLLECTOR_BIND` / `COLLECTOR_PUBLIC_URL` for your VPN.
+3. `docker compose up -d --build`, then register the first account with the setup token from the backend log.
+4. Click **Connect a server** to add other machines.
-<img width="2879" height="1499" alt="image" src="https://github.com/user-attachments/assets/a1541d08-5cb5-4926-b553-d1512159c265" />
+Every step, with the reasons and pitfalls: [Deploying on a server](docs/deployment.md), [Deploy behind Traefik](docs/deploy-traefik.md), [Adding servers](docs/adding-servers.md).
+To update: `git pull && docker compose up -d --build`.
## Features
-- **One dashboard for every machine**: CPU, RAM, load, swap, network totals and
- uptime per server, plus disk and inode usage for **every mounted filesystem**
- (root, data disks, NFS/SMB shares, ZFS pools).
-- **This machine at a glance**: live CPU, memory and disk charts for the machine
- running the dashboard, with the last 30 minutes of history.
-- **Statistics for any range**: a page with charts from the last hour to everything ever
- recorded, per server (resources, distributions, busy hours, storage with a
- "full in about N days" estimate, reliability), per container (cards and details) and for the
- whole fleet (incidents over time, containers by state, availability, rankings). Long
- ranges stay cheap because history is summarised into hourly, daily, weekly and monthly rows.
-- **Container details**: containers sit in a collapsible list per server, sorted by
- name, with problems (unhealthy, restarting, stopped) shown even when it's closed.
- Open a container to see CPU, memory used/limit, processes, network and disk I/O,
- uptime, ports, health status and CPU/memory history. Stopped containers show how
- they ended (exit code, or "out of memory"), and a **Recent changes** list shows
- containers that appeared, disappeared or came up on a different image.
-- **System health per server**: reboots, OOM-killer activity, kernel fault flags,
- clock synchronisation and pending reboots, plus (with the optional system helper)
- whether the last shutdown was clean and which process the OOM killer stopped.
-- **Network at a glance**: which ports each server listens on (and which are reachable
- from other machines), whether its firewall configuration changed, and, if you turn
- it on, whether it can still reach the internet.
-- **Incidents with sensible alert rules**: disk (with per-mount overrides), inodes,
- memory, swap, load per CPU core, container restart loops, failing healthchecks,
- reboots and crashes, OOM kills, kernel faults, unsynchronised clocks, an
- unreachable or slow Docker daemon, containers that crash or are killed for running
- out of memory, containers that vanish or change image, possible memory leaks, new
- ports opened to the network, firewall changes, lost internet or DNS, and servers
- that stop reporting. One incident per problem, opened only after a sustained
- breach where that makes sense and resolved automatically when it clears.
- Thresholds are editable by admins.
-- **Availability checks (like Uptime Kuma, but from your own machines)**: track the
- services you run — **HTTP(s)** status, a **keyword** on a page, a **value in a JSON
- reply**, a **TCP port**, a **TLS certificate's** expiry, a **DNS** record, or an
- **ICMP ping**. Each check runs from the servers you pick (so "down when all fail" or
- "down when any fails" tells a broken service apart from a broken network path), on its
- own interval with retries, and opens an ordinary incident when it fails. The collector
- runs the checks itself — no shell, nothing more than it already has — and a **Test**
- button tries a check from its servers before you save it. One page shows every check
- grouped by tag, with a heartbeat strip, 24 h / 30 d / 1 y uptime, response time and the
- machine each check ran from.
-- **Add servers with one command and one click**: click **Connect a server**, run
- the generated command on the new machine, then click **Add**. The command carries
- a single-use token, so only an admin can add machines.
-- **Built to be exposed carefully**: a public dashboard behind Traefik, with
- collectors reporting over your VPN instead. Collectors run with no Docker
- socket and no capabilities; a separate read-only proxy answers Docker queries.
-- **Per-server check interval** (15 s to 15 min), set from the dashboard.
-- **Works on phones**: bottom navigation, touch-sized controls and layouts that
- fit from 320 px wide screens up.
-- **Accounts with roles**: the first account (created with a setup token) is the
- admin; other accounts get a read-only view. Passwords must be at least 16
- characters. Redis-backed sessions and login/registration rate limiting.
-- **Account security**: optional two-factor sign-in (authenticator app and single-use
- recovery codes), **required for admins by default**; change your password, review
- and end your sessions, and reset a locked-out account from the host.
-- **Incident agent** (optional): diagnoses every warning and critical incident from masked evidence, with each
- claim tied to the data; reuses a diagnosis when the same problem returns within a day; resolves the incident once
- its fix holds; adds the diagnosis to notifications; chat about any incident. Monthly budget, per-model prices and
- who-sees-what in Admin. See [Incident agent](docs/assistant.md).
-
-<img width="2879" height="1499" alt="image" src="https://github.com/user-attachments/assets/ed90a777-6b28-404c-94d6-34c2b465cc0e" />
+### Monitoring
+- **Every machine**: CPU, RAM, load, swap, network totals and uptime per server, plus disk and inode usage for **every mounted filesystem** (root, data disks, NFS/SMB shares, ZFS pools).
+- **Containers**: a collapsible list per server, with problems (unhealthy, restarting, stopped) visible even when it's closed. Per container: CPU, memory used/limit, processes, network and disk I/O, ports, health and history. Stopped containers show how they ended (exit code or out of memory). **Recent changes** shows containers that appeared, disappeared or changed image.
+- **System health**: reboots, OOM kills, kernel fault flags, clock sync and pending reboots. With the optional system helper, also whether the last shutdown was clean and which process the OOM killer stopped.
+- **Network**: listening ports (and which are reachable from other machines), firewall changes and, optionally, internet reachability.
+- **Statistics for any range**, from the last hour to all time, per server, per container and for the whole fleet, including a "disk full in about N days" estimate. Long ranges stay fast because history is rolled up into hourly, daily, weekly and monthly rows.
+
+<img width="2879" height="1499" alt="Infradeck screenshot" src="https://github.com/user-attachments/assets/a1541d08-5cb5-4926-b553-d1512159c265" />
+
+### Availability checks
+Like Uptime Kuma, but run from your own machines: **HTTP(s)** status, a **keyword** on a page, a **value in a JSON reply**, a **TCP port**, **TLS certificate** expiry, a **DNS** record or an **ICMP ping**.
+- Each check runs from the servers you pick, with "down when all fail" or "down when any fails".
+- Own interval and retries; a **Test** button tries it before you save.
+- One page for every check, grouped by tag, with a heartbeat strip, 24 h / 30 d / 1 y uptime and response times.
+- The collector runs checks itself: no shell, no extra permissions.
+
+<img width="2879" height="1499" alt="Infradeck incident agent" src="https://github.com/user-attachments/assets/ed90a777-6b28-404c-94d6-34c2b465cc0e" />
+
+### Incidents and alerts
+Rules for disk (with per-mount overrides), inodes, memory, swap, load per core, restart loops, failing healthchecks, reboots and crashes, OOM kills, kernel faults, clock drift, an unreachable Docker daemon, vanished or changed containers, possible memory leaks, newly opened ports, firewall changes, lost internet or DNS, and servers that stop reporting. Thresholds are editable by admins. Full list: [Alerts and incidents](docs/alerts.md).
+
+### Incident agent (optional)
+Set `OPENAI_API_KEY` and the agent diagnoses every warning and critical incident from **masked** evidence, ties each claim to the data, proposes a fix, watches whether it holds and adds the diagnosis to your notifications. You can also chat about any incident. Monthly budget, per-model prices and who sees what are set in Admin. **It reads; it never runs commands.** See [Incident agent](docs/assistant.md).
+
+<img width="2879" height="1499" alt="Infradeck dashboard" src="https://github.com/user-attachments/assets/4331b563-9537-4393-882d-f0dbe5a1aedd" />
+
+### Accounts and everyday use
+- Roles: the first account is the admin; others get a read-only view.
+- Two-factor sign-in (authenticator app + recovery codes), **required for admins by default**. Review and end sessions; reset a locked-out account from the host.
+- Per-server check interval from 15 s to 15 min.
+- Works on phones, from 320 px wide screens up.
## Architecture
@@ -124,7 +151,7 @@ flowchart LR
backend --> pg[(PostgreSQL)]
backend --> redis[(Redis)]
localc["collector"] --> gate
- localc -->|"unix socket"| dproxy["docker-proxy<br/>6 read-only requests"]
+ localc -->|"unix socket"| dproxy["docker-proxy<br/>read-only requests"]
helper["system-helper (optional)<br/>CAP_SYSLOG, no network"] -.->|"summary file"| localc
end
browser["Browser"] -->|"https://your-domain"| rproxy["Reverse proxy<br/>(handles HTTPS)"]
@@ -139,72 +166,33 @@ flowchart LR
linkStyle default stroke:#A09D95,stroke-width:1px
```
-1. Find the one-time **setup token** in the backend log:
- `docker compose logs backend | grep "setup token"`. Open http://localhost:5173
- and register an account with it. Use a password of at least 16 characters (a
- few random words work well). The first account is the admin.
-2. This machine appears under **New servers detected**. Click **Add**.
-3. Metrics start arriving within a few seconds, and the charts at the top of the
- dashboard start following this machine.
-
-Health check: http://localhost:5173/api/health
-
-```bash
-docker compose logs -f backend frontend collector # follow logs
-docker compose --profile system-events up -d # also run the optional system helper
-docker compose down # stop (data volumes are kept)
-```
-
-To try **Connect a server** on the same machine, set `COLLECTOR_IMAGE` and
-`DOCKER_PROXY_IMAGE` in `.env` to `infradeck-collector:latest` and
-`infradeck-docker-proxy:latest` (the images Compose just built). Other machines
-need published images; see [Publishing the collector images](docs/deployment.md#publishing-the-collector-images).
+What each container does and why it's there: [The containers](docs/containers.md).
-## Deploying on a server
-
-The server stack (`docker-compose.server.yml`) publishes the dashboard through the reverse proxy you already run
-(a ready-made file for **Traefik** is in [`deploy/`](deploy)) and serves the collector endpoints only on a separate listener bound to your **VPN address**. In short:
+## Security
-1. `cp example.env .env`, then set `POSTGRES_PASSWORD`, `REDIS_PASSWORD`, `DASHBOARD_DOMAIN`, `TRUSTED_PROXIES` and
- `COMPOSE_FILE=docker-compose.server.yml`, with Traefik `docker-compose.server.yml:deploy/traefik.yml` and your
- Traefik names (`COMPOSE_FILE` matters: without it Compose uses the development stack).
-2. Generate `SECRETS_KEY` (needed for two-factor sign-in) and set `COLLECTOR_BIND` / `COLLECTOR_PUBLIC_URL` for your VPN.
-3. `docker compose up -d --build`, then register the first account with the setup token from the backend log.
-4. Click **Connect a server** to add other machines.
+[SECURITY.md](SECURITY.md) has the full picture: what each component can touch and the limits of each protection. In short:
-Every step, with the reasons and the pitfalls, is in [Deploying on a server](docs/deployment.md) (with Traefik:
-[Deploy Infradeck behind Traefik](docs/deploy-traefik.md)) and
-[Adding servers](docs/adding-servers.md). To update later: `git pull` and `docker compose up -d --build`.
+- **Collectors are unprivileged.** No Docker socket, no capabilities, read-only filesystem. Only a separate read-only proxy (no network, a short allowlist of requests, stripped answers) touches the socket.
+- **Collector endpoints are not public.** On the server stack they exist only on the gate bound to your VPN address. Joining needs a single-use token plus an admin's click.
+- **Nothing the dashboard serves runs on your hosts.** Remote machines install signed, digest-pinned images.
+- **Fresh installs can't be claimed**: the first account needs a setup token. Passwords need 16 characters; two-factor is required for admins by default.
+- **Browser protections**: cross-site requests are refused; strict Content-Security-Policy and HSTS.
+- **Secrets at rest**: tokens stored only as hashes, passwords with bcrypt, two-factor secrets encrypted with your `SECRETS_KEY`.
## Documentation
-Full documentation is in the [`docs/`](docs/README.md) folder:
+Everything is in [`docs/`](docs/README.md):
| | |
|---|---|
-| [Metrics: what every number means](docs/metrics.md) | How CPU %, load, memory, swap, disk, inodes, network and container figures are measured, and their limits. |
-| [Statistics](docs/statistics.md) | History from the last hour to all time, per server, per container and for the whole fleet. |
-| [The dashboard and system health](docs/dashboard.md) | Fleet cards, storage, the Network and System rows, the optional system helper. |
+| [Metrics](docs/metrics.md) | What every number means, how it's measured and its limits. |
+| [Statistics](docs/statistics.md) | History per server, per container and for the whole fleet. |
+| [Dashboard and system health](docs/dashboard.md) | Fleet cards, storage, the Network and System rows, the system helper. |
| [Alerts and incidents](docs/alerts.md) | Every rule and its default thresholds. |
-| [Accounts and two-factor sign-in](docs/accounts.md) | Roles, passwords, authenticator codes, recovery and reset. |
-| [The containers](docs/containers.md) | What each container (backend, PostgreSQL, Redis, collector, Docker proxy, helpers) does and why it is there. |
-| [Deploying](docs/deployment.md), [Adding servers](docs/adding-servers.md), [Configuration](docs/configuration.md), [Troubleshooting](docs/troubleshooting.md) | Installing, running and fixing it. |
-| [Development](docs/development.md), [Database schema](docs/database.md), [API overview](docs/api.md), [Incident agent](docs/assistant.md) | For contributors. |
-
-## Security
-
-[SECURITY.md](SECURITY.md) has the full picture: what each component can touch, and the limits of each
-protection. In short:
-
-- **Collectors are unprivileged.** No Docker socket, no capabilities, a read-only filesystem. Only a separate
- read-only proxy (no network, four allowed requests, stripped answers) touches the socket.
-- **Collector endpoints are not public.** On the server stack they exist only on the gate bound to your VPN
- address, and joining needs a single-use token plus an admin's click. Remote machines install signed,
- digest-pinned images; the dashboard never serves code that runs on your hosts.
-- **Fresh installs can't be claimed** (the first account needs a setup token), passwords need 16 characters,
- and two-factor sign-in is **required for admins by default**.
-- **Browser protections:** cross-site requests are refused, with a strict Content-Security-Policy and HSTS.
-- **Secrets at rest:** tokens stored only as hashes, passwords with bcrypt, two-factor secrets encrypted with your `SECRETS_KEY`.
+| [Accounts and two-factor](docs/accounts.md) | Roles, passwords, authenticator codes, recovery and reset. |
+| [The containers](docs/containers.md) | What each container does and why it's there. |
+| [Deploying](docs/deployment.md) · [Adding servers](docs/adding-servers.md) · [Configuration](docs/configuration.md) · [Troubleshooting](docs/troubleshooting.md) | Installing, running and fixing it. |
+| [Development](docs/development.md) · [Database schema](docs/database.md) · [API](docs/api.md) · [Incident agent](docs/assistant.md) | For contributors. |
## Development and tests
@@ -219,4 +207,4 @@ cd src/frontend && node --test #
## License
-Copyright (c) 2026 Karlo Kajba Šimanić. Licensed under the GNU Affero General Public License v3.0; see [LICENSE](LICENSE).
+Copyright (c) 2026 Karlo Kajba Šimanić. Licensed under the [GNU Affero General Public License v3.0](LICENSE).