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.
Python ai-agentsaiopsdashboarddockerfastapihomelabincident-managementllmmonitoringopenaireactroot-cause-analysisself-hosteduptime-monitoring
refactor(deploy): move the Traefik labels into deploy/traefik.yml
Karlo Kajba Šimanićaac6059e77c5
diff --git a/README.md b/README.mdindex 6c21f63..d6686f3 100644--- a/README.md+++ b/README.md@@ -162,17 +162,19 @@ need published images; see [Publishing the collector images](docs/deployment.md### Deploying on a server-The server stack (`docker-compose.server.yml`) publishes the dashboard through an existing **Traefik** and-serves the collector endpoints only on a separate listener bound to your **VPN address**. In short:+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:-1. `cp example.env .env`, then set `POSTGRES_PASSWORD`, `REDIS_PASSWORD`, `DASHBOARD_DOMAIN`, your Traefik names and- `COMPOSE_FILE=docker-compose.server.yml` (the last one matters: without it Compose uses the development stack).+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 -f docker-compose.server.yml up -d --build`, then register the first account with the setup token from the backend log.+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.-Every step, with the reasons and the pitfalls, is in [Deploying on a server](docs/deployment.md) and-[Adding servers](docs/adding-servers.md). To update later: `git pull` and `docker compose -f docker-compose.server.yml up -d --build`.+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`.## Documentationdiff --git a/deploy/traefik.yml b/deploy/traefik.ymlnew file mode 100644index 0000000..ae7d5e1--- /dev/null+++ b/deploy/traefik.yml@@ -0,0 +1,22 @@+# Publishes the server stack through an existing Traefik (step by step: docs/deploy-traefik.md).+# Add it after the server file in .env:+# COMPOSE_FILE=docker-compose.server.yml:deploy/traefik.yml+# Then a plain `docker compose up -d --build` uses both. All values come from .env: DASHBOARD_DOMAIN+# (required), TRAEFIK_ROUTER, TRAEFIK_ENTRYPOINT, TRAEFIK_CERT_RESOLVER and TRAEFIK_NETWORK (defaults shown).+# Also set TRUSTED_PROXIES to the subnet of Traefik's network, so each client keeps its own address.+services:+ frontend:+ networks:+ - traefik+ labels:+ - traefik.enable=true+ - traefik.docker.network=${TRAEFIK_NETWORK:-traefik_default}+ - traefik.http.routers.${TRAEFIK_ROUTER:-infradeck}.rule=Host(`${DASHBOARD_DOMAIN:?Set DASHBOARD_DOMAIN in .env}`)+ - traefik.http.routers.${TRAEFIK_ROUTER:-infradeck}.entrypoints=${TRAEFIK_ENTRYPOINT:-websecure}+ - traefik.http.routers.${TRAEFIK_ROUTER:-infradeck}.tls.certresolver=${TRAEFIK_CERT_RESOLVER:-letsencrypt}+ - traefik.http.services.${TRAEFIK_ROUTER:-infradeck}.loadbalancer.server.port=80++networks:+ traefik:+ external: true+ name: ${TRAEFIK_NETWORK:-traefik_default} # Traefik's Docker network; same value as the label abovediff --git a/docker-compose.server.yml b/docker-compose.server.ymlindex eb689ef..8a2ca13 100644--- a/docker-compose.server.yml+++ b/docker-compose.server.yml@@ -1,9 +1,12 @@-# Server stack, published over HTTPS by an existing Traefik.-# docker compose -f docker-compose.server.yml up -d --build-# Nothing here needs editing: your domain and Traefik names come from .env (see example.env),+# Server stack, published over HTTPS by the reverse proxy you already run (Traefik, Caddy, nginx, ...).+# Your proxy reaches the dashboard on 127.0.0.1:5173, or over the `front` network if it runs in Docker.+# Set COMPOSE_FILE in .env, adding the ready-made file for your proxy from deploy/ if there is one+# (see docs/deployment.md), then run a plain `docker compose up -d --build`:+# COMPOSE_FILE=docker-compose.server.yml:deploy/traefik.yml (Traefik)+# COMPOSE_FILE=docker-compose.server.yml (any other reverse proxy)+# Nothing here needs editing: your settings come from .env (see example.env),# so `git pull` can always update this file. Don't copy it under another name: Compose# prefers compose.yml (the development stack) when two default-named files exist.-# Tip: put COMPOSE_FILE=docker-compose.server.yml in .env so a plain `docker compose ...` uses it.services:postgres:image: postgres:16-alpine@@ -53,7 +56,7 @@ services:REDIS_URL: redis://:${REDIS_PASSWORD:?Set REDIS_PASSWORD in .env (generate one with openssl rand -hex 24)}@redis:6379/0OPENAI_API_KEY: ${OPENAI_API_KEY:-}AGENT_MODEL: ${AGENT_MODEL:-gpt-5-mini}- # Served over HTTPS via Traefik, so the login cookie is HTTPS-only.+ # Served over HTTPS by your reverse proxy, so the login cookie is HTTPS-only.SESSION_COOKIE_SECURE: ${SESSION_COOKIE_SECURE:-true}# Only the first account can register; set to true to let others sign up.ALLOW_REGISTRATION: ${ALLOW_REGISTRATION:-false}@@ -292,26 +295,15 @@ services:environment:# Address or network of your reverse proxy; empty trusts nobody's X-Forwarded-For.TRUSTED_PROXIES: ${TRUSTED_PROXIES:-}- # Serves the dashboard and proxies /api to the backend; Traefik publishes it+ # Serves the dashboard and proxies /api to the backend; your reverse proxy publishes it# over HTTPS on your domain. The plain-HTTP port is bound to localhost only# (set FRONTEND_BIND=0.0.0.0 to also allow direct LAN/VPN access).ports:- - "${FRONTEND_BIND:-127.0.0.1}:${FRONTEND_PORT:-8080}:80"+ - "${FRONTEND_BIND:-127.0.0.1}:${FRONTEND_PORT:-5173}:80"volumes:# Public listener only: collector endpoints are refused here (see the collector-gate service).- ./docker/nginx.strict.conf:/etc/nginx/conf.d/default.conf:ro- networks:- - front- - traefik- labels:- - traefik.enable=true- # All values come from .env: DASHBOARD_DOMAIN (required), TRAEFIK_ROUTER, TRAEFIK_ENTRYPOINT,- # TRAEFIK_CERT_RESOLVER and TRAEFIK_NETWORK (defaults shown).- - traefik.docker.network=${TRAEFIK_NETWORK:-traefik_default}- - traefik.http.routers.${TRAEFIK_ROUTER:-infradeck}.rule=Host(`${DASHBOARD_DOMAIN:?Set DASHBOARD_DOMAIN in .env}`)- - traefik.http.routers.${TRAEFIK_ROUTER:-infradeck}.entrypoints=${TRAEFIK_ENTRYPOINT:-websecure}- - traefik.http.routers.${TRAEFIK_ROUTER:-infradeck}.tls.certresolver=${TRAEFIK_CERT_RESOLVER:-letsencrypt}- - traefik.http.services.${TRAEFIK_ROUTER:-infradeck}.loadbalancer.server.port=80+ networks: [front]depends_on:backend:condition: service_healthy@@ -323,9 +315,6 @@ networks:internal: truefront:collector:- traefik:- external: true- name: ${TRAEFIK_NETWORK:-traefik_default} # Traefik's Docker network; same value as the label abovevolumes:postgres_data:diff --git a/docs/README.md b/docs/README.mdindex 93bafc3..8722ff9 100644--- a/docs/README.md+++ b/docs/README.md@@ -18,7 +18,8 @@ The [README](../README.md) is the short version: what the project is, how to sta| Page | What is in it ||---|---|| [The containers and why each one exists](containers.md) | Every container in the stack: what it does, how it works, why it is separate, and what happens when it stops. |-| [Deploying on a server](deployment.md) | The server stack behind Traefik, the VPN collector gate, publishing the collector images, updating, running without Traefik. |+| [Deploying on a server](deployment.md) | The server stack behind your reverse proxy (ready-made for Traefik), the VPN collector gate, publishing the collector images, updating, other proxies. |+| [Deploy Infradeck behind Traefik](deploy-traefik.md) | Step by step on a server that already runs Traefik: `.env`, first start, admin account, verifying, upgrading and rolling back, common errors. || [Adding servers](adding-servers.md) | **Connect a server**, what its command does, how registration and approval work, networking. || [Configuration](configuration.md) | Every `.env` setting for the stack, the collector and the frontend build. || [Troubleshooting](troubleshooting.md) | Symptoms and what to check. |diff --git a/docs/configuration.md b/docs/configuration.mdindex 472215e..2af40ee 100644--- a/docs/configuration.md+++ b/docs/configuration.md@@ -30,7 +30,7 @@ Every setting below is listed, with no values, in [`example.env`](../example.env| `BACKEND_PORT` | `8060` | Development stack only: the host port (on `127.0.0.1`) where the backend is published for debugging. The server stack publishes no backend port. || `FRONTEND_PORT` | `5173` | Dashboard port on the host. || `DASHBOARD_DOMAIN` | *(required on a server)* | Domain of the dashboard, without `https://` (server file). |-| `TRAEFIK_ENTRYPOINT` / `TRAEFIK_CERT_RESOLVER` / `TRAEFIK_NETWORK` / `TRAEFIK_ROUTER` | `websecure` / `letsencrypt` / `traefik_default` / `infradeck` | Your Traefik names (server file). |+| `TRAEFIK_ENTRYPOINT` / `TRAEFIK_CERT_RESOLVER` / `TRAEFIK_NETWORK` / `TRAEFIK_ROUTER` | `websecure` / `letsencrypt` / `traefik_default` / `infradeck` | Your Traefik names (`deploy/traefik.yml`). || `CORS_ORIGINS` | `http://localhost:5173` (dev), `https://<DASHBOARD_DOMAIN>` (server file) | Comma-separated origins. Also the allow-list for the cross-site request check: a state-changing request from any other origin is refused unless its `Origin` matches the `Host` the dashboard was reached on. Add your dashboard URL if something in front rewrites `Host`. || `LOGIN_RATE_LIMIT` / `LOGIN_RATE_WINDOW_SECONDS` | `5` / `60` | Login attempts per IP and per email. || `REGISTER_RATE_LIMIT` / `REGISTER_RATE_WINDOW_SECONDS` | `3` / `3600` | Registrations per IP. |@@ -42,7 +42,7 @@ Every setting below is listed, with no values, in [`example.env`](../example.env| `INFRADECK_ENROLL_KEY` | empty | Lets the stack's own collector skip approval. || `INFRADECK_SERVER_NAME` | host's hostname | Name shown for the stack's own machine. || `DOMAIN` | `localhost` | Domain for the optional Caddy profile. |-| `COMPOSE_FILE` | – | Set to `docker-compose.server.yml` on a server so plain `docker compose` uses it. |+| `COMPOSE_FILE` | – | On a server: `docker-compose.server.yml`, with Traefik `docker-compose.server.yml:deploy/traefik.yml`, so plain `docker compose` uses them. || `LIVE_GRAPH_REFRESH_INTERVAL_SECONDS` | `3` | How often the dashboard refreshes (server file; applied when the frontend image is built). || `INFRADECK_CHECK_INTERVAL_SECONDS` | `60` | Initial check interval of the stack's own collector (server file); the dashboard setting overrides it. |diff --git a/docs/containers.md b/docs/containers.mdindex d06dec7..a83c41e 100644--- a/docs/containers.md+++ b/docs/containers.md@@ -285,7 +285,7 @@ keep coming.## infradeck-collector-gate (server stack only)**What it does.** The only way to reach the four collector endpoints (register, poll registration,-enroll, ingest) when the stack runs behind Traefik.+enroll, ingest) when the server stack runs behind a reverse proxy.**How it works.** A plain `nginx:alpine` with [`docker/nginx.collector.conf`](../docker/nginx.collector.conf)and two listeners:@@ -296,7 +296,7 @@ and two listeners:Everything else answers `404`. The gate marks each request with the listener it came through, and thebackend (with `COLLECTOR_ACCESS=strict`) accepts collector traffic only when that mark is present. The-gate is not on Traefik's network, so other apps behind the same Traefik can't reach the collector+gate is not on the reverse proxy's network, so other apps behind the same proxy can't reach the collectorendpoints either.**Why this approach.** The dashboard itself may be public on the internet, but the endpoints that@@ -350,7 +350,7 @@ it obtains and renews a Let's Encrypt certificate for `DOMAIN` and proxies everyStart it with `docker compose --profile https up -d`.**Why Caddy here.** It handles certificates with no configuration beyond the domain name. The server-stack doesn't include it because it expects an existing Traefik to handle HTTPS (see+stack doesn't include it because it expects the reverse proxy you already run to handle HTTPS (see[Deploying](deployment.md)).## Volumesdiff --git a/docs/dashboard.md b/docs/dashboard.mdindex f175af4..b0bfc02 100644--- a/docs/dashboard.md+++ b/docs/dashboard.md@@ -50,7 +50,7 @@ the kernel log and the login records, which the collector deliberately can'tread. A separate container does:```bash-docker compose --profile system-events up -d # add -f docker-compose.server.yml on a server+docker compose --profile system-events up -d # on a server, with COMPOSE_FILE set in .env```It runs with a single capability (`CAP_SYSLOG`), no network and a read-onlydiff --git a/docs/deploy-traefik.md b/docs/deploy-traefik.mdnew file mode 100644index 0000000..871639f--- /dev/null+++ b/docs/deploy-traefik.md@@ -0,0 +1,232 @@+[← Documentation](README.md)++# Deploy Infradeck behind Traefik++When you're done, the dashboard runs on your server at `https://<your-domain>` behind your existing Traefik, and+remote machines can report to it over your VPN.++This guide covers one setup: a server where Traefik already runs in Docker. It uses the server stack+(`docker-compose.server.yml`) plus the ready-made [`deploy/traefik.yml`](../deploy/traefik.yml). You don't edit+either file; your settings go into `.env`. For another reverse proxy, see+[Deploying on a server](deployment.md#other-reverse-proxies). Already running Infradeck behind Traefik? Go to+[Upgrade an existing install](#upgrade-an-existing-install).++## Before you start++- **Docker with Compose v2** on the server. Check with `docker compose version`.+- **Traefik running in Docker** with the Docker provider, an HTTPS entrypoint and a certificate resolver.+ Infradeck labels its frontend with `traefik.enable=true`, so `exposedByDefault=false` is fine.+- **A DNS record** for `<your-domain>` pointing at the server.+- **Optional, for remote machines:** a VPN (WireGuard, OpenVPN, Tailscale) between the server and those machines.++Look up three names from your Traefik setup. Step 2 needs them.++| Name | Where to find it | Infradeck's default |+|---|---|---|+| HTTPS entrypoint | Traefik's static configuration, under `entryPoints:` | `websecure` |+| Certificate resolver | Traefik's static configuration, under `certificatesResolvers:` | `letsencrypt` |+| Traefik's Docker network | `docker inspect <traefik-container> --format '{{json .NetworkSettings.Networks}}'` | `traefik_default` |++All commands below run on the server, in the `infradeck` folder from step 1.++## 1. Get the code++```bash+git clone https://github.com/karloks2005/Infradeck.git infradeck+cd infradeck+cp example.env .env+```++`.env` holds your passwords and keys. Keep it on the server and never commit it.++## 2. Fill in `.env`++Find the subnet of Traefik's network. Replace `traefik_default` if your network has another name:++```bash+docker network inspect traefik_default --format '{{range .IPAM.Config}}{{.Subnet}}{{end}}'+```++It prints one range, for example:++```text+172.18.0.0/16+```++Open `.env` and set these lines. Leave every other line empty.++```bash+COMPOSE_FILE=docker-compose.server.yml:deploy/traefik.yml+POSTGRES_PASSWORD=<output of: openssl rand -hex 32>+REDIS_PASSWORD=<output of: openssl rand -hex 24>+DASHBOARD_DOMAIN=<your-domain, without https://>+TRUSTED_PROXIES=<the subnet printed above>+TRAEFIK_ENTRYPOINT=<your HTTPS entrypoint, or empty for websecure>+TRAEFIK_CERT_RESOLVER=<your certificate resolver, or empty for letsencrypt>+TRAEFIK_NETWORK=<Traefik's network, or empty for traefik_default>+```++- `COMPOSE_FILE` makes every plain `docker compose ...` command use both files.+- `TRUSTED_PROXIES` lets Traefik tell Infradeck each visitor's real address. Without it all visitors share+ Traefik's address, and one person's failed sign-ins lock everyone out for a minute. Every container on that+ network is trusted too, so keep only containers you trust on Traefik's network.++## 3. Start the stack++Run `docker compose` without `-f` in this step and every later one. `-f` replaces `COMPOSE_FILE`, which leaves+out `deploy/traefik.yml`, and Traefik stops serving the dashboard.++```bash+docker compose up -d --build+docker compose ps+```++The first build takes a few minutes. It worked when every service shows `running` and `backend` shows+`healthy`. Traefik's dashboard lists a router named `infradeck`.++## 4. Add the secrets key++The key encrypts two-factor secrets and notification addresses. Two-factor sign-in is required for admins and+can't be set up without it.++```bash+docker compose run --rm backend python -m src.backend.secrets_box+```++It prints one key:++```text+<a 44-character key ending in =>+```++Put it in `.env` as `SECRETS_KEY=<that key>`, and keep a copy with your other secrets, outside database backups.+Then apply it:++```bash+docker compose up -d+```++## 5. Create the admin account++Print the one-time setup token:++```bash+docker compose logs backend | grep "setup token"+```++```text+infradeck-backend | First-run setup token: <token> (needed to create the first account; shown again at every start until it exists)+```++Open `https://<your-domain>`, register, and enter the token. This first account is the admin, and registration+closes after it. Set up two-factor sign-in when the dashboard asks.++## 6. Let remote machines report (optional)++Collectors never use the public domain. They report to the collector gate, published on your VPN address.++Bind the gate to the VPN address, never `0.0.0.0`: Docker's published ports bypass `ufw` and similar firewalls,+so `0.0.0.0` puts the collector endpoints on the internet. Add to `.env`, with `<vpn-address>` the server's own+address on the VPN:++```bash+COLLECTOR_BIND=<vpn-address>+COLLECTOR_PUBLIC_URL=http://<vpn-address>:8081/api+COLLECTOR_IMAGE=<collector image digest>+DOCKER_PROXY_IMAGE=<Docker proxy image digest>+```++The two image lines come from the Publish images workflow; see+[Publishing the collector images](deployment.md#publishing-the-collector-images). Apply the change:++```bash+docker compose up -d+```++Then open **Connect a server** in the dashboard and follow [Adding servers](adding-servers.md).++## Verify++1. Check the response from outside the server:+ ```bash+ curl -sI https://<your-domain> | grep -i strict-transport-security+ ```+ ```text+ strict-transport-security: max-age=15552000+ ```+ That header comes from Infradeck, so the request went through Traefik to the dashboard over HTTPS.+2. Sign in and open **Account › Sessions**. Your session shows your own public address. An address from+ Traefik's subnet means `TRUSTED_PROXIES` is missing or wrong.+3. If you did step 6: the new machine appears on the dashboard within a minute of running its command.++## Upgrade an existing install++Back up the database first. The backend updates the schema when it starts:++```bash+docker compose exec -T postgres pg_dump -U infradeck -d infradeck -Fc > infradeck-before-upgrade.dump+```++Use your `POSTGRES_USER` and `POSTGRES_DB` instead of `infradeck` if you set them.++**From a version with the Traefik labels in `docker-compose.server.yml`:** the labels moved to+`deploy/traefik.yml`. Set these in `.env` before you pull, or Traefik stops serving the dashboard:++```bash+COMPOSE_FILE=docker-compose.server.yml:deploy/traefik.yml+TRUSTED_PROXIES=<subnet of Traefik's network, see step 2>+```++The dashboard's local port is `127.0.0.1:5173` again. Set `FRONTEND_PORT` if something on the server relies on+another one.++Update:++```bash+git pull+docker compose up -d --build+```++Rebuild everything; a service you don't rebuild keeps running the old code. Check the result as in+[Verify](#verify).++### Roll back++Go back to the commit you ran before, and rebuild:++```bash+git log --oneline -5+git checkout <previous-commit>+docker compose up -d --build+```++If that version still had the Traefik labels in `docker-compose.server.yml`, set+`COMPOSE_FILE=docker-compose.server.yml` in `.env` first.++If the older backend doesn't start on the upgraded database, restore the backup:++<!-- TODO: verify this restore on a test install -->+```bash+docker compose stop backend agent-worker collector+docker compose exec -T postgres pg_restore -U infradeck -d infradeck --clean --if-exists < infradeck-before-upgrade.dump+docker compose up -d+```++## Troubleshooting++| Symptom | Cause | Fix |+|---|---|---|+| `network traefik_default declared as external, but could not be found` | `TRAEFIK_NETWORK` doesn't match Traefik's network. | Set it to the name from [Before you start](#before-you-start), then `docker compose up -d`. |+| Traefik answers `404 page not found` | `deploy/traefik.yml` isn't loaded, so the frontend has no labels. | Check `COMPOSE_FILE` in `.env`, then `docker compose up -d` without `-f`. |+| Traefik answers `Bad Gateway` or `Gateway Timeout` | Traefik and the frontend aren't on the same network. | Set `TRAEFIK_NETWORK` to the network Traefik is attached to, then `docker compose up -d`. |+| Certificate warning in the browser | `TRAEFIK_CERT_RESOLVER` doesn't match a resolver in Traefik, so Traefik serves its default certificate. | Fix the name, then `docker compose up -d`. Traefik's log shows any ACME error. |+| Signed out right after signing in | The dashboard was opened over `http://`, or `SESSION_COOKIE_SECURE` was set to `false`. | Use `https://<your-domain>` and leave `SESSION_COOKIE_SECURE` empty. |+| Everyone is locked out after a few failed sign-ins | `TRUSTED_PROXIES` is empty or wrong, so all visitors share Traefik's address. | Set it as in step 2, then `docker compose up -d`. |+| The frontend restarts over and over | `TRUSTED_PROXIES` contains something other than IP addresses and CIDR ranges. | `docker compose logs frontend` names the bad value. Fix it in `.env`. |++More symptoms: [Troubleshooting](troubleshooting.md).++## Next++- [Adding servers](adding-servers.md): put collectors on your other machines.+- [Deploying on a server](deployment.md): why the server stack is built this way, and other reverse proxies.diff --git a/docs/deployment.md b/docs/deployment.mdindex cdf6894..ede8a10 100644--- a/docs/deployment.md+++ b/docs/deployment.md@@ -1,13 +1,21 @@[← Documentation](README.md)-# Deploying on a server (behind Traefik)+# Deploying on a serverThere are two Compose files:| File | Use | Differences ||---|---|---|| `compose.yml` | Laptop / development (the default when you run `docker compose` without `-f`) | Dashboard on port 5173 on all interfaces; plain HTTP; optional Caddy (`--profile https`). |-| `docker-compose.server.yml` | Server behind an existing Traefik | Traefik labels and network; HTTPS-only session cookie; only the first account can register; port 5173 bound to `127.0.0.1`; no Caddy; **collector endpoints removed from the public side** and served by a separate collector gate on your VPN address. |+| `docker-compose.server.yml` | Server behind your reverse proxy (Traefik, Caddy, nginx, ...) | HTTPS-only session cookie; only the first account can register; port 5173 bound to `127.0.0.1`; no Caddy; **collector endpoints removed from the public side** and served by a separate collector gate on your VPN address. |++The server stack works behind any reverse proxy. For some proxies there is also a ready-made file in+[`deploy/`](../deploy) that you add on top of it, so the proxy picks the dashboard up without any setup of its own:++| Your proxy | Add | What it adds |+|---|---|---|+| Traefik | `deploy/traefik.yml` | The Traefik labels (router, entrypoint, certificate resolver) and Traefik's Docker network. Step-by-step: [Deploy Infradeck behind Traefik](deploy-traefik.md). |+| Anything else | nothing | Point your proxy at the dashboard port, `127.0.0.1:5173` (see [Other reverse proxies](#other-reverse-proxies)). |## 1. Create `.env` on the server@@ -24,26 +32,36 @@ Then set at least these:|---|---|---|| `POSTGRES_PASSWORD` | *(required)* | A long random password for the bundled database. || `REDIS_PASSWORD` | *(required)* | A long random password for Redis, which holds the login sessions. Letters and digits only (`openssl rand -hex 24`). |-| `DASHBOARD_DOMAIN` | *(required)* | Your domain, without `https://`. Used for the Traefik router. |+| `DASHBOARD_DOMAIN` | *(required)* | Your domain, without `https://`. Used for the allowed origin (CORS) and the Traefik router. || `TRUSTED_PROXIES` | empty | The subnet of your reverse proxy's Docker network, for Traefik `docker network inspect traefik_default --format '{{range .IPAM.Config}}{{.Subnet}}{{end}}'`. Without it every client shares Traefik's address, so one person's failed sign-ins can lock everyone out for a minute. See [Reverse proxies](#reverse-proxies-and-client-addresses). |-| `TRAEFIK_ENTRYPOINT` | `websecure` | Your Traefik HTTPS entrypoint name. |-| `TRAEFIK_CERT_RESOLVER` | `letsencrypt` | Your Traefik certificate resolver name. |-| `TRAEFIK_NETWORK` | `traefik_default` | The Docker network Traefik is attached to. |-| `TRAEFIK_ROUTER` | `infradeck` | Name of this dashboard's Traefik router and service; change it only if it clashes with another one. |-| `COMPOSE_FILE` | `docker-compose.server.yml` | Makes plain `docker compose ...` commands use the server file (see below). |+| `TRAEFIK_ENTRYPOINT` | `websecure` | Traefik only: your HTTPS entrypoint name. |+| `TRAEFIK_CERT_RESOLVER` | `letsencrypt` | Traefik only: your certificate resolver name. |+| `TRAEFIK_NETWORK` | `traefik_default` | Traefik only: the Docker network Traefik is attached to. |+| `TRAEFIK_ROUTER` | `infradeck` | Traefik only: name of this dashboard's router and service; change it only if it clashes with another one. |+| `COMPOSE_FILE` | `docker-compose.server.yml`, with Traefik `docker-compose.server.yml:deploy/traefik.yml` | Makes plain `docker compose ...` commands use the server file and your proxy's file (see below). || `SECRETS_KEY` | *(strongly recommended)* | Encrypts two-factor secrets and notification addresses. Two-factor is required for admins by default and can't be set up without it. Generate with `docker compose run --rm backend python -m src.backend.secrets_box`. || `OPENAI_API_KEY`, `AGENT_MODEL` | empty, `gpt-5-mini` | Optional: the incident agent's diagnoses and chat. See [Incident agent](assistant.md#setting-it-up). |-Find the network with `docker network ls` or+With Traefik, find its network with `docker network ls` or`docker inspect <traefik-container> --format '{{json .NetworkSettings.Networks}}'`.The entrypoint and resolver names are in Traefik's static configuration(`entryPoints:` / `certificatesResolvers:`).## 2. Use the right Compose file-`COMPOSE_FILE=docker-compose.server.yml` in `.env` matters. Without it, Compose picks-`compose.yml` (the development stack), and an `up` would replace the server containers-with ones that have no Traefik labels and open registration.+`COMPOSE_FILE` in `.env` matters. Without it, Compose picks `compose.yml` (the development+stack), and an `up` would replace the server containers with ones that have open registration+and serve the collector endpoints publicly. Set it to the server file, followed by your proxy's+file from `deploy/` if you use one, separated by `:`:++```bash+COMPOSE_FILE=docker-compose.server.yml:deploy/traefik.yml # with Traefik+COMPOSE_FILE=docker-compose.server.yml # any other proxy+```++All commands below are plain `docker compose ...` and rely on it. Don't add+`-f docker-compose.server.yml`: `-f` replaces `COMPOSE_FILE`, so it would leave out your proxy's+file (with Traefik, the dashboard would disappear from your domain until the next plain `up`).**Don't copy the server file under another name** (for example `docker-compose.yml`). Ifboth `compose.yml` and `docker-compose.yml` exist, Compose silently uses `compose.yml`, and@@ -53,14 +71,14 @@ into `.env`, delete the copy, and continue with `docker-compose.server.yml`.## 3. Start it```bash-docker compose -f docker-compose.server.yml up -d --build+docker compose up -d --build```Open `https://<your-domain>` and register your account right away. The firstaccount needs the **setup token** (`docker compose logs backend | grep "setup token"`,or the value of `ADMIN_BOOTSTRAP_TOKEN` if you set one), so a stranger who finds afresh deployment can't claim it; then registration closes. That first account is-the admin. Traefik terminates HTTPS with its own certificates; the stack needs no+the admin. Your reverse proxy terminates HTTPS with its own certificates; the stack needs nocertificate configuration.The public address serves only the dashboard. Collectors don't use it; set up@@ -110,7 +128,7 @@ git tag v0.9.2 && git push origin v0.9.2 # the version in src/backend/configcredentials. Check from any machine that isn't signed in to GHCR:`docker manifest inspect ghcr.io/<owner>/infradeck/collector:<version>`.3. Rebuild the stack so the backend knows the images:- `docker compose -f docker-compose.server.yml up -d --build`.+ `docker compose up -d --build`.**Connect a server** won't generate a command until both images are set.@@ -118,7 +136,7 @@ git tag v0.9.2 && git push origin v0.9.2 # the version in src/backend/config```bashgit pull-docker compose -f docker-compose.server.yml up -d --build+docker compose up -d --build```Always rebuild **all** services (don't name individual ones). The backend,@@ -126,6 +144,13 @@ frontend, collector, Docker proxy and system helper each have their code builtinto their image, so a service that isn't rebuilt keeps running the old version.The database schema is updated automatically when the backend starts.+**Upgrading from a version with the Traefik labels in `docker-compose.server.yml`:** they moved to+`deploy/traefik.yml`. Before you update, change `.env` to+`COMPOSE_FILE=docker-compose.server.yml:deploy/traefik.yml`. Without it the dashboard starts+without the labels and Traefik stops serving your domain; adding it and running `docker compose up -d` again+fixes that.+The dashboard port's default is `127.0.0.1:5173` again; set `FRONTEND_PORT` if you rely on another one.+**Upgrading from a version that had no `REDIS_PASSWORD`:** add one to `.env` first(`echo "REDIS_PASSWORD=$(openssl rand -hex 24)" >> .env`), then update as above. Compose refuses to startwithout it. This version also separates the containers onto three networks and stores login sessions@@ -140,11 +165,12 @@ compose project). Collectors started from `collector-compose.yml` need<diagram - What each step updates: git pull → source on disk; docker compose up -d --build → backend, frontend, collector, docker-proxy and gate containers rebuilt and recreated; git tag → Publish images workflow → new digests → .env and a fresh Connect a server command for remote machines; show that skipping --build leaves the old image running>-## Without Traefik+## Other reverse proxies-- **Another reverse proxy (nginx, Caddy, HAProxy, ...):** use the **server stack** (`docker-compose.server.yml`),- not the development stack, and point your proxy at its dashboard port (`127.0.0.1:5173` by default; the- Traefik labels are simply unused). The server stack is the one that keeps the collector endpoints off the+- **Another reverse proxy (nginx, Caddy, HAProxy, a tunnel connector, ...):** use the **server stack**+ (`docker-compose.server.yml`) on its own, not the development stack, and point your proxy at its dashboard+ port (`127.0.0.1:5173` by default). A proxy that runs in Docker can instead join the stack's `front` network+ and reach `frontend:80`. The server stack is the one that keeps the collector endpoints off thepublic side, registration closed and the session cookie HTTPS-only. Terminate HTTPS in your proxy, have itsend `X-Forwarded-For`, and set `TRUSTED_PROXIES` to its address (see below).- **Caddy profile (`--profile https`, development stack): private use only.** It publishes the developmentdiff --git a/docs/development.md b/docs/development.mdindex 84f0c12..5ad4628 100644--- a/docs/development.md+++ b/docs/development.md@@ -69,7 +69,8 @@ PostgreSQL database to run it there as well as on SQLite.```textcompose.yml development stack (default for `docker compose`)-docker-compose.server.yml server stack behind Traefik+docker-compose.server.yml server stack behind your reverse proxy+deploy/ ready-made additions for a reverse proxy (deploy/traefik.yml)collector-compose.yml collector-only stack for monitored machinesREADME.md what it is and how to start it (the short version)docs/ the full documentation (start at docs/README.md)diff --git a/docs/troubleshooting.md b/docs/troubleshooting.mdindex 024e006..70038da 100644--- a/docs/troubleshooting.md+++ b/docs/troubleshooting.md@@ -6,8 +6,8 @@|---|---|| A new machine never shows up under **New servers detected** | `docker logs infradeck-collector` on that machine. "Could not reach …" means the address in the command isn't reachable from it (firewall, `localhost`, wrong IP/domain). || Collector log says "Backend no longer accepts server …" | The server was deleted on the dashboard; it is asking to join again, so click **Add** or **Dismiss**. |-| `network traefik_default declared as external, but could not be found` | You're using `docker-compose.server.yml` on a machine without that Traefik network. Use `compose.yml` for development, or set `TRAEFIK_NETWORK` in `.env` to the network Traefik is really on. |-| Dashboard shows old behaviour after a code change or `git pull` | Rebuild **all** services with `docker compose up -d --build` (with `-f docker-compose.server.yml` on a server unless `COMPOSE_FILE` is set) and hard-refresh the browser (Ctrl+Shift+R). |+| `network traefik_default declared as external, but could not be found` | You're using `deploy/traefik.yml` on a machine without that Traefik network. Set `TRAEFIK_NETWORK` in `.env` to the network Traefik is really on, or, without Traefik, drop `deploy/traefik.yml` from `COMPOSE_FILE`. |+| Dashboard shows old behaviour after a code change or `git pull` | Rebuild **all** services with `docker compose up -d --build` (on a server with `COMPOSE_FILE` set in `.env`) and hard-refresh the browser (Ctrl+Shift+R). || "The machine running the dashboard isn't reporting yet" at the top | The stack's own collector hasn't checked in: add it under **New servers detected**, then wait one check interval. If it is reporting, its image is outdated: `docker exec infradeck-collector grep -c dashboard_host /app/collector.py` prints `0`. Rebuild it (`docker compose build --no-cache collector && docker compose up -d collector`). || A server shows only `/` and no **Storage** bars for other disks | Its collector predates per-mount reporting. Install a newer collector image (run a freshly generated command, or `docker compose -f collector-compose.yml up -d --build`). A disk mounted after the collector started appears after a collector restart. || Logged out after opening the dashboard at a new address | Login cookies belong to the address they were set on; log in again. |diff --git a/example.env b/example.envindex 2c854df..a5f5677 100644--- a/example.env+++ b/example.env@@ -6,18 +6,21 @@# empty: an empty value means the default written in its comment. Never commit your filled-in .env.## Which compose file reads a setting:-# both compose.yml (laptop / development) and docker-compose.server.yml (server behind Traefik)+# both compose.yml (laptop / development) and docker-compose.server.yml (server behind a reverse proxy)# server docker-compose.server.yml only# dev compose.yml only+# traefik deploy/traefik.yml only (added on top of the server file)# Remote machines added with "Connect a server" need none of this; see the last sections.# =============================================================================# Which compose file to use# =============================================================================-# On a server set this to: docker-compose.server.yml-# Then a plain `docker compose ...` uses the server file. Left empty, Compose picks compose.yml (the-# development stack) and would replace your server containers with ones that have no Traefik labels.+# On a server set this to the server file, plus your proxy's file from deploy/ if there is one:+# docker-compose.server.yml:deploy/traefik.yml (Traefik)+# docker-compose.server.yml (any other reverse proxy)+# Then a plain `docker compose ...` uses them. Left empty, Compose picks compose.yml (the development+# stack) and would replace your server containers with ones that serve the collector endpoints publicly.COMPOSE_FILE=# =============================================================================@@ -34,7 +37,7 @@ POSTGRES_PASSWORD=REDIS_PASSWORD=# REQUIRED (server). The domain the dashboard is served on, without https:// and without a slash,-# for example infradeck.example.com. Used for the Traefik router and the default CORS_ORIGINS.+# for example infradeck.example.com. Used for the default CORS_ORIGINS and the Traefik router.DASHBOARD_DOMAIN=# =============================================================================@@ -75,10 +78,10 @@ SECRETS_KEY=TRUSTED_PROXIES=# =============================================================================-# Traefik (server)+# Traefik (traefik)# =============================================================================-# (server) Names from your Traefik setup: the HTTPS entrypoint and certificate resolver from Traefik's+# (traefik) Names from your Traefik setup: the HTTPS entrypoint and certificate resolver from Traefik's# static configuration (entryPoints / certificatesResolvers), and the Docker network Traefik is on# (docker network ls, or: docker inspect <traefik-container> --format '{{json .NetworkSettings.Networks}}').# Defaults: websecure, letsencrypt, traefik_default@@ -86,7 +89,7 @@ TRAEFIK_ENTRYPOINT=TRAEFIK_CERT_RESOLVER=TRAEFIK_NETWORK=-# (server) Name of this dashboard's Traefik router and service. Change it only if it clashes with+# (traefik) Name of this dashboard's Traefik router and service. Change it only if it clashes with# another one. Default: infradeckTRAEFIK_ROUTER=@@ -207,7 +210,7 @@ INFRADECK_CONNECTIVITY_TARGETS=# =============================================================================# (both) Address and port of the dashboard's plain-HTTP port on this machine. 127.0.0.1 keeps it-# reachable only from here (Traefik still reaches it over the Docker network); 0.0.0.0 allows LAN/VPN.+# reachable only from here (a proxy in Docker can still reach it over the Docker network); 0.0.0.0 allows LAN/VPN.# Defaults: 0.0.0.0 (dev), 127.0.0.1 (server); port 5173FRONTEND_BIND=FRONTEND_PORT=