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.

fix: docker compose fixes

karloks2005072017eb16f1
diff --git a/README.md b/README.md
index 0c10970..acded9a 100644
--- a/README.md
+++ b/README.md
@@ -95,8 +95,8 @@ flowchart LR
(register, poll, enroll, ingest). It publishes one port on your **VPN address**
and is not attached to Traefik's network.
- The **backend** (FastAPI) stores metrics in PostgreSQL and sessions and rate
- limits in Redis. Its own port is published on `127.0.0.1:8000` only in the
- development stack.
+ limits in Redis. Its own port is published on `127.0.0.1:8060` only in the
+ development stack (change it with `BACKEND_PORT`).
- **Collectors** only make outgoing requests. Monitored machines need no open
ports, only a route to the collector gate.
- The **Docker proxy** is the only container that mounts `/var/run/docker.sock`.
@@ -662,6 +662,7 @@ policy on, the account is asked to set up two-factor again at its next sign-in.
| `SECRETS_KEY` | empty | Key that encrypts two-factor secrets. Required for two-factor sign-in and for the "require two-factor for admins" policy to be enforced. Generate with `python -m src.backend.secrets_box`; comma-separated keys allow rotation. |
| `ADMIN_BOOTSTRAP_TOKEN` | generated at start | Setup token for the first account. Leave empty to have one generated and printed in the backend log until the first account exists. |
| `FRONTEND_BIND` | `0.0.0.0` (dev), `127.0.0.1` (server file) | Interface for the dashboard's plain-HTTP port. |
+| `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` / `homelab` | Your Traefik names (server file). |
@@ -684,7 +685,7 @@ policy on, the account is asked to set up two-factor again at its next sign-in.
| Variable | Default | Description |
|---|---|---|
-| `HOMELAB_API_URL` | `http://localhost:8000` | Dashboard API address, e.g. `https://dashboard.example.com/api`. |
+| `HOMELAB_API_URL` | `http://localhost:8060` | Dashboard API address, e.g. `https://dashboard.example.com/api`. |
| `HOMELAB_JOIN_TOKEN` | empty | Single-use token from **Connect a server**; required over the VPN listener. |
| `HOMELAB_ENROLL_KEY` | empty | Join immediately instead of waiting for approval. |
| `HOMELAB_SERVER_NAME` | host's `/etc/hostname` | Name shown on the dashboard. |
@@ -780,12 +781,12 @@ python -m venv venv && source venv/bin/activate
pip install -r requirements.txt
docker run -d --name homelab-dev-redis -p 6379:6379 redis:7-alpine # if Redis isn't running
DATABASE_URL=sqlite:///./dev.db REDIS_URL=redis://localhost:6379/0 \
- uvicorn src.backend.main:app --reload --host 0.0.0.0 --port 8000
+ uvicorn src.backend.main:app --reload --host 0.0.0.0 --port 8060
```
### Frontend dev server
-Node 20 (`.nvmrc`). The Vite dev server proxies `/api` to `localhost:8000`,
+Node 20 (`.nvmrc`). The Vite dev server proxies `/api` to `localhost:8060` (set `BACKEND_URL` to point it elsewhere),
matching the production nginx setup.
```bash
diff --git a/SECURITY.md b/SECURITY.md
index 41c6d0e..abd79aa 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -181,7 +181,7 @@ the public side at all.
What this still depends on:
- The backend trusts the `X-Collector-Via` header nginx sets. That is safe only while nothing
- untrusted can reach the backend directly (port 8000 is not published in the server stack; don't
+ untrusted can reach the backend directly (the backend's port is not published in the server stack; don't
add other containers to its network).
- Anyone on your VPN can reach the gate. With a valid join token they can request to join, and an
admin still has to approve them; ingest additionally needs a server's token.
diff --git a/compose.yml b/compose.yml
index 6e36e93..954dfd7 100644
--- a/compose.yml
+++ b/compose.yml
@@ -48,14 +48,19 @@ services:
CORS_ORIGINS: ${CORS_ORIGINS:-http://localhost:5173}
# Key that encrypts stored secrets such as two-factor secrets (generate: docker compose run --rm backend python -m src.backend.secrets_box).
SECRETS_KEY: ${SECRETS_KEY:-}
+ # Setup token for the very first account. Empty: one is generated and printed in the backend log.
+ ADMIN_BOOTSTRAP_TOKEN: ${ADMIN_BOOTSTRAP_TOKEN:-}
+ # How long a token from "Connect a server" stays valid, in seconds.
+ JOIN_TOKEN_TTL_SECONDS: ${JOIN_TOKEN_TTL_SECONDS:-900}
# Connect a server panel: images remote hosts install, and the address they reach this dashboard at.
COLLECTOR_IMAGE: ${COLLECTOR_IMAGE:-}
DOCKER_PROXY_IMAGE: ${DOCKER_PROXY_IMAGE:-}
COLLECTOR_PUBLIC_URL: ${COLLECTOR_PUBLIC_URL:-}
# Browsers and remote collectors reach the API through the frontend at /api;
- # the direct port is only published on this machine for debugging.
+ # the direct port is only published on this machine for debugging. 8060 keeps it clear of the
+ # many other tools that use 8000; set BACKEND_PORT in .env if 8060 is taken too.
ports:
- - "127.0.0.1:8000:8000"
+ - "127.0.0.1:${BACKEND_PORT:-8060}:8000"
depends_on:
postgres:
condition: service_healthy
diff --git a/docker-compose.server.yml b/docker-compose.server.yml
index acece3c..1694b53 100644
--- a/docker-compose.server.yml
+++ b/docker-compose.server.yml
@@ -59,6 +59,10 @@ services:
REGISTER_RATE_LIMIT: ${REGISTER_RATE_LIMIT:-3}
REGISTER_RATE_WINDOW_SECONDS: ${REGISTER_RATE_WINDOW_SECONDS:-3600}
ADMIN_ALERT_WEBHOOK_URL: ${ADMIN_ALERT_WEBHOOK_URL:-}
+ # Setup token for the very first account. Empty: one is generated and printed in the backend log.
+ ADMIN_BOOTSTRAP_TOKEN: ${ADMIN_BOOTSTRAP_TOKEN:-}
+ # How long a token from "Connect a server" stays valid, in seconds.
+ JOIN_TOKEN_TTL_SECONDS: ${JOIN_TOKEN_TTL_SECONDS:-900}
# Key that encrypts stored secrets such as two-factor secrets (generate: docker compose run --rm backend python -m src.backend.secrets_box).
SECRETS_KEY: ${SECRETS_KEY:-}
# Collector endpoints answer only through the collector-gate container (VPN or internal).
diff --git a/example.env b/example.env
index a16950b..38318bf 100644
--- a/example.env
+++ b/example.env
@@ -77,6 +77,14 @@ SESSION_TTL_SECONDS=86400
# the same domain.
SESSION_COOKIE_NAME=homie_session
+# Setup token for the very first account (the one that becomes the admin).
+# Leave it commented: the backend then makes one up and prints it in its log
+# ("docker compose logs backend | grep 'setup token'") until the first account exists.
+# ADMIN_BOOTSTRAP_TOKEN=
+
+# How long the token created by "Connect a server" stays valid, in seconds.
+# JOIN_TOKEN_TTL_SECONDS=900
+
# =============================================================================
# Rate limits (brute-force protection)
# =============================================================================
diff --git a/src/agent/collector.py b/src/agent/collector.py
index e290763..30673d7 100644
--- a/src/agent/collector.py
+++ b/src/agent/collector.py
@@ -930,7 +930,7 @@ def resolve_credentials(api_url: str) -> tuple[int, str]:
def run_collector() -> None:
- api_url = os.getenv("HOMELAB_API_URL", "http://localhost:8000")
+ api_url = os.getenv("HOMELAB_API_URL", "http://localhost:8060")
server_id, token = resolve_credentials(api_url)
interval = max(15, int(os.getenv("HOMELAB_CHECK_INTERVAL_SECONDS", "60")))
print(f"Collector started for server {server_id}; API={api_url}", flush=True)
diff --git a/src/frontend/vite.config.js b/src/frontend/vite.config.js
index bccdfc8..f345d0c 100644
--- a/src/frontend/vite.config.js
+++ b/src/frontend/vite.config.js
@@ -7,7 +7,8 @@ export default defineConfig({
// Mirror the production nginx route so `npm run dev` also talks to /api.
server: {
proxy: {
- '/api': { target: 'http://localhost:8000', rewrite: (path) => path.replace(/^\/api/, '') },
+ // 8060 is where the development stack publishes the backend (BACKEND_PORT in .env).
+ '/api': { target: process.env.BACKEND_URL || 'http://localhost:8060', rewrite: (path) => path.replace(/^\/api/, '') },
},
},
})