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.

refactor(deploy): move the Traefik labels into deploy/traefik.yml

Karlo Kajba Šimanićaac6059e77c5
diff --git a/README.md b/README.md
index 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`.
## Documentation
diff --git a/deploy/traefik.yml b/deploy/traefik.yml
new file mode 100644
index 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 above
diff --git a/docker-compose.server.yml b/docker-compose.server.yml
index 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/0
OPENAI_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: true
front:
collector:
- traefik:
- external: true
- name: ${TRAEFIK_NETWORK:-traefik_default} # Traefik's Docker network; same value as the label above
volumes:
postgres_data:
diff --git a/docs/README.md b/docs/README.md
index 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.md
index 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.md
index 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 the
backend (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 collector
endpoints 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 every
Start 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)).
## Volumes
diff --git a/docs/dashboard.md b/docs/dashboard.md
index 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't
read. 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-only
diff --git a/docs/deploy-traefik.md b/docs/deploy-traefik.md
new file mode 100644
index 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.md
index 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 server
There 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`). If
both `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 first
account 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 a
fresh 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 no
certificate 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/config
credentials. 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
```bash
git 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 built
into 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 start
without 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 the
public side, registration closed and the session cookie HTTPS-only. Terminate HTTPS in your proxy, have it
send `X-Forwarded-For`, and set `TRUSTED_PROXIES` to its address (see below).
- **Caddy profile (`--profile https`, development stack): private use only.** It publishes the development
diff --git a/docs/development.md b/docs/development.md
index 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.
```text
compose.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 machines
README.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.md
index 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.env
index 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: infradeck
TRAEFIK_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 5173
FRONTEND_BIND=
FRONTEND_PORT=