chore(observability): externalize stack from root compose files

Manage now connects to existing Grafana/Prometheus/Alertmanager instances
and never deploys its own stack.

- docker-compose.yml / docker-compose.dev.yml: removed prometheus, loki,
  alloy, grafana, alertmanager, node-exporter services, the monitoring
  network, and observability named volumes; they now ship only backend +
  frontend. Dev frontend now joins the web network so the Vite dev proxy
  can reach the backend.
- backend: alertmanager_url default is now empty; /api/monitoring/alerts
  and /alertmanager-status return graceful "not configured" responses
  when ALERTMANAGER_URL is unset. Added not-configured tests.
- docker-compose.observability.yml: kept as the optional standalone
  example; header clarifies Manage does not deploy it.
- Removed orphaned combined monitoring/prometheus/prometheus.yml
  (standalone stack uses prometheus.standalone.yml).
- Docs (README, REQUIREMENTS decision log, monitoring-logging-design,
  observability-runbooks, context.md, MIGRATION_PLAN, frontend/README,
  CHANGELOG) updated to the connect-to-existing model.

VITE_GRAFANA_URL / VITE_PROMETHEUS_URL remain as optional frontend
deep-link overrides. .env.example still needs a manual update (safety
policy blocks assistant edits): set ALERTMANAGER_URL empty/optional and
move standalone-only vars out of the root file.
This commit is contained in:
Developer
2026-06-23 21:20:07 +00:00
parent 4d520ab0e3
commit d4f95b64d4
16 changed files with 146 additions and 493 deletions
+19
View File
@@ -4,6 +4,25 @@ All notable changes to Manage. Breaking changes are marked with **BREAKING**.
## [Unreleased]
### Changed — Observability is now external only
- **Removed** all observability services from `docker-compose.yml` and
`docker-compose.dev.yml`. They now deploy **only** the backend and frontend.
The `monitoring` network and the `prometheus`/`loki`/`alloy`/`grafana`/
`alertmanager`/`node-exporter` services and their named volumes were deleted,
and the `GRAFANA_APP_HOST` Traefik rule was removed.
- Manage now connects to **existing** Grafana/Prometheus/Alertmanager instances
and never ships its own stack. The previous in-compose stack is preserved as
an optional, deploy-it-yourself example in `docker-compose.observability.yml`
(config under `monitoring/`, documented in `docs/observability-runbooks.md`).
- The backend `alertmanager_url` default is now empty. The
`/api/monitoring/alerts` and `/alertmanager-status` endpoints return a
graceful "not configured" response when `ALERTMANAGER_URL` is unset.
- Removed the now-orphaned combined `monitoring/prometheus/prometheus.yml`; the
standalone stack uses `monitoring/prometheus/prometheus.standalone.yml`.
- `VITE_GRAFANA_URL`/`VITE_PROMETHEUS_URL` remain as optional frontend deep-link
overrides. `ALERTMANAGER_URL`/`ALERTMANAGER_WEBHOOK_URL` are optional.
### Added — Service registry
- Runtime **service registry** persisted in the backend SQLite database. External
+5 -3
View File
@@ -44,6 +44,8 @@ Open the app at <http://localhost:8080>.
The production Compose file requires OIDC and Traefik variables; see [Configuration](#configuration) below. Copy `.env.example` to `.env`, fill in the required values, and export them in your shell before running `docker compose up`.
> **Observability is external.** Manage only ships its **backend** and **frontend**. It does **not** deploy Grafana, Prometheus, Loki, Alertmanager, Alloy, or Node Exporter. The backend exposes a `/metrics` endpoint and optional Alertmanager proxy endpoints so an *existing* observability deployment can scrape and consume them. For a ready-to-run example stack you can deploy alongside Manage, see [`docker-compose.observability.yml`](docker-compose.observability.yml) and [`docs/observability-runbooks.md`](docs/observability-runbooks.md).
Local development with hot reload:
```bash
@@ -81,7 +83,6 @@ Production-style example with shell exports:
```bash
export BACKEND_APP_HOST=api.manage.example.com
export FRONTEND_APP_HOST=manage.example.com
export GRAFANA_APP_HOST=grafana.manage.example.com
export CERT_RESOLVER=letsencrypt
export VITE_OIDC_ISSUER=https://auth.example.com/application/o/manage/
export VITE_OIDC_CLIENT_ID=manage
@@ -97,7 +98,7 @@ docker compose up --build
Inline one-liner example:
```bash
BACKEND_APP_HOST=api.manage.example.com FRONTEND_APP_HOST=manage.example.com GRAFANA_APP_HOST=grafana.manage.example.com CERT_RESOLVER=letsencrypt VITE_OIDC_ISSUER=https://auth.example.com/application/o/manage/ VITE_OIDC_CLIENT_ID=manage VITE_OIDC_REDIRECT_URI=https://manage.example.com/oidc/callback VITE_OIDC_POST_LOGOUT_REDIRECT_URI=https://manage.example.com/ VITE_GRAFANA_URL=https://grafana.manage.example.com VITE_PROMETHEUS_URL=https://prometheus.manage.example.com docker compose up --build
BACKEND_APP_HOST=api.manage.example.com FRONTEND_APP_HOST=manage.example.com CERT_RESOLVER=letsencrypt VITE_OIDC_ISSUER=https://auth.example.com/application/o/manage/ VITE_OIDC_CLIENT_ID=manage VITE_OIDC_REDIRECT_URI=https://manage.example.com/oidc/callback VITE_OIDC_POST_LOGOUT_REDIRECT_URI=https://manage.example.com/ VITE_GRAFANA_URL=https://grafana.manage.example.com VITE_PROMETHEUS_URL=https://prometheus.manage.example.com docker compose up --build
```
For local development, no SSH key is required unless you want to connect to remote SSH machines later:
@@ -182,6 +183,7 @@ cd frontend && npx tsc --noEmit && npm run build
- Jellyfin server root URL required (not `/web`). The client strips trailing `/web` defensively.
- SSH commands run through `/bin/sh -c` regardless of remote login shell.
- Job templates are shell-quoted. Add new templates in `backend/src/media_library_viewer_api/jobs.py`.
- Root-level Docker Compose files are provided for production (`docker-compose.yml`) and local development (`docker-compose.dev.yml`), and both rely on Compose interpolation rather than `env_file` entries.
- Root-level Docker Compose files are provided for production (`docker-compose.yml`) and local development (`docker-compose.dev.yml`), and both rely on Compose interpolation rather than `env_file` entries. They deploy **only** the backend and frontend; Manage never deploys its own observability stack (see `docker-compose.observability.yml` for an optional standalone example).
- The configurable dashboard stores widget instances in the backend SQLite settings database. New installs seed default Jellyfin activity and Backups widgets automatically.
- Grafana and Prometheus widget adapters resolve URLs from service records configured in the app; `VITE_GRAFANA_URL` / `VITE_PROMETHEUS_URL` are only used for frontend deep-links. No credentials are stored in widget config; service API keys are encrypted at rest with `MANAGE_ENCRYPTION_KEY`.
- `ALERTMANAGER_URL` is optional. When unset, the Alertmanager proxy endpoints return graceful "not configured" responses instead of erroring.
@@ -55,7 +55,7 @@ class Settings(BaseSettings):
# Observability
prometheus_enabled: bool = True
prometheus_file_sd_dir: str = "/app/backend/.cache/prometheus-file-sd"
alertmanager_url: str = "http://alertmanager:9093"
alertmanager_url: str = ""
alertmanager_webhook_url: str = "" # Optional receiver for alertmanager webhook notifications
# Remote paths
@@ -88,11 +88,13 @@ def get_alertmanager_alerts() -> dict[str, Any]:
"""Return a summary of active Alertmanager alerts for the UI.
Proxies the Alertmanager `/api/v1/alerts` endpoint and reshapes the payload
into a stable, UI-friendly format. If Alertmanager is unreachable, the
endpoint returns an empty summary and logs the failure so the UI can still
render a health card instead of an error page.
into a stable, UI-friendly format. If Alertmanager is unreachable (or not
configured via ``ALERTMANAGER_URL``), the endpoint returns an empty summary
so the UI can still render a health card instead of an error page.
"""
session, base_url = _alertmanager_client()
if not base_url:
return {"total": 0, "by_severity": {}, "alerts": [], "error": "alertmanager_not_configured"}
try:
response = session.get(f"{base_url}/api/v1/alerts", timeout=5)
response.raise_for_status()
@@ -115,9 +117,12 @@ def get_alertmanager_status() -> dict[str, Any]:
Uses the Alertmanager `/api/v2/status` endpoint and exposes only the high-
level fields the UI needs: uptime, version, and whether the cluster is
healthy.
healthy. Returns ``up=False`` when Alertmanager is unreachable or not
configured via ``ALERTMANAGER_URL``.
"""
session, base_url = _alertmanager_client()
if not base_url:
return {"up": False, "version": "", "uptime": ""}
try:
response = session.get(f"{base_url}/api/v2/status", timeout=5)
response.raise_for_status()
+21
View File
@@ -677,6 +677,17 @@ class TestAlertmanager:
assert data["total"] == 0
assert data["error"] == "alertmanager_unreachable"
def test_alerts_endpoint_when_not_configured(self, test_client):
with patch("media_library_viewer_api.routers.monitoring._alertmanager_client") as mock_client:
session = MagicMock()
mock_client.return_value = (session, "")
response = test_client.get("/api/monitoring/alerts")
assert response.status_code == 200
data = response.json()
assert data["total"] == 0
assert data["error"] == "alertmanager_not_configured"
session.get.assert_not_called()
def test_alerts_endpoint_returns_summary(self, test_client):
with patch("media_library_viewer_api.routers.monitoring._alertmanager_client") as mock_client:
session = MagicMock()
@@ -700,6 +711,16 @@ class TestAlertmanager:
assert data["by_severity"]["critical"] == 1
assert data["alerts"][0]["name"] == "BackupJobFailed"
def test_alertmanager_status_endpoint_when_not_configured(self, test_client):
with patch("media_library_viewer_api.routers.monitoring._alertmanager_client") as mock_client:
session = MagicMock()
mock_client.return_value = (session, "")
response = test_client.get("/api/monitoring/alertmanager-status")
assert response.status_code == 200
data = response.json()
assert data["up"] is False
session.get.assert_not_called()
def test_alertmanager_status_endpoint_when_unreachable(self, test_client):
with patch("media_library_viewer_api.routers.monitoring._alertmanager_client") as mock_client:
session = MagicMock()
-1
View File
@@ -369,7 +369,6 @@ async def test_ssh_task_adapter_records_history_on_run(client):
fake_result = SimpleNamespace(exit_status=0, stdout="hi\n", stderr="")
fake_client = SimpleNamespace(run=lambda *a, **k: fake_result)
from media_library_viewer_api.services.task_runner import build_ssh_client
from media_library_viewer_api.widgets.sources import SshTaskWidgetSource
adapter = SshTaskWidgetSource()
+28 -2
View File
@@ -1,6 +1,16 @@
# Code Context
> **Status (2026-06-23):** Manage no longer deploys an observability stack.
> The root `docker-compose.yml` / `docker-compose.dev.yml` ship **only** the
> backend and frontend; Grafana, Prometheus, Loki, Alertmanager, Alloy, and Node
> Exporter were removed from them. Manage connects to **existing** instances.
> The standalone example stack lives in `docker-compose.observability.yml`. Some
> snippets below still reference the former in-compose services and are kept as
> historical context; treat `docker-compose.observability.yml` as authoritative
> for the stack layout.
## Files Retrieved
1. `docker-compose.yml` (lines 1262) production Compose stack; defines observability services and Traefik routing.
2. `docker-compose.dev.yml` (lines 1234) development Compose stack; same observability services but with host ports exposed and auth disabled.
3. `.env.example` (lines 155) template with all required environment variables for the stack, including Prometheus/Grafana/Alertmanager/Alloy/Loki and Node Exporter settings.
@@ -20,7 +30,9 @@
## Key Code
### Backend `/metrics` endpoint
`backend/src/media_library_viewer_api/main.py`:
```python
@app.middleware("http")
async def enforce_jwt_auth(request: Request, call_next):
@@ -36,7 +48,9 @@ def metrics() -> Response:
```
### Metrics emitted by the backend
`backend/src/media_library_viewer_api/observability.py`:
```python
REQUESTS_TOTAL = Counter("manage_api_requests_total", "Total API requests", ["method", "path", "status_code"])
REQUEST_DURATION = Histogram("manage_api_request_duration_seconds", "API request duration", ["method", "path"], ...)
@@ -48,7 +62,9 @@ MAIL_QUEUE_SIZE = Counter("manage_mail_queue_messages_total", "Total messages en
```
### Prometheus scrape configuration
`monitoring/prometheus/prometheus.yml`:
```yaml
scrape_configs:
- job_name: manage-backend
@@ -71,7 +87,9 @@ scrape_configs:
```
### Backend-managed remote Node Exporter targets
`backend/src/media_library_viewer_api/services/targets.py`:
```python
def build_node_exporter_targets(store: SettingsStore) -> list[dict[str, Any]]:
...
@@ -96,6 +114,7 @@ The observability stack is a standard self-hosted Prometheus/Grafana/Loki/Alertm
- **Alertmanager** routes alerts by severity (critical vs warning) and delivers email notifications (and optionally a webhook back to the backend).
The backend bridges the stack with the application:
- It exposes `/metrics` (unauthenticated, along with `/api/health` and `/api/version`).
- On startup it writes `${PROMETHEUS_FILE_SD_DIR}/node_exporter_targets.json` based on enabled SSH machines in the settings store.
- It provides proxy endpoints (`/api/monitoring/alerts`, `/api/monitoring/alertmanager-status`, `/api/monitoring/prometheus-targets`) consumed by the frontend.
@@ -105,6 +124,7 @@ The backend bridges the stack with the application:
Open `monitoring/prometheus/prometheus.yml` first to understand what is scraped and how the backend is wired, then read `backend/src/media_library_viewer_api/observability.py` to see the metric names and labels. For environment requirements, read `.env.example`.
## Supervisor coordination
Not needed — this is a read-only scouting summary.
---
@@ -113,7 +133,7 @@ Not needed — this is a read-only scouting summary.
## 1. Observability services defined in Compose
Both `docker-compose.yml` and `docker-compose.dev.yml` define the following services:
Both `docker-compose.yml` and `docker-compose.dev.yml` define **only the backend and frontend**. The observability services (Prometheus, Loki, Grafana, Alertmanager, Alloy, Node Exporter) were extracted to the standalone `docker-compose.observability.yml` example stack and are **no longer** deployed by Manage. Summary of what remains in the app compose files:
| Service | Image | Internal endpoint | Purpose |
|---------|-------|-------------------|---------|
@@ -126,6 +146,7 @@ Both `docker-compose.yml` and `docker-compose.dev.yml` define the following serv
| `backend` | Build from `backend/Dockerfile` | `http://backend:8000` | FastAPI app exposing `/metrics` |
Differences:
- Production (`docker-compose.yml`): services attach to an external `web` network for Traefik, use `expose` instead of host ports for most services, and require OIDC/auth variables.
- Development (`docker-compose.dev.yml`): Prometheus/Grafana/Loki/Alertmanager/Node Exporter are published on host ports `9090`, `3000`, `3100`, `9093`, `9100`; auth is disabled (`AUTH_ENABLED=false`).
@@ -134,6 +155,7 @@ Differences:
From `.env.example` and the Compose files, the variables relevant to the observability stack are:
### Backend / metrics
- `PROMETHEUS_ENABLED` enable metrics endpoint (set to `"true"` in both compose files).
- `PROMETHEUS_FILE_SD_DIR` directory where the backend writes `node_exporter_targets.json` (default `/app/backend/.cache/prometheus-file-sd`).
- `ALERTMANAGER_URL` backend proxy target (default `http://alertmanager:9093`).
@@ -141,6 +163,7 @@ From `.env.example` and the Compose files, the variables relevant to the observa
- `BACKEND_CACHE_DIR` host directory mounted into backend and Prometheus for file-SD.
### Grafana
- `GRAFANA_APP_HOST` public hostname for Grafana (production; required).
- `GRAFANA_APP_PORT` defaults to `3000`.
- `GRAFANA_APP_NAME` defaults to `grafana`.
@@ -152,16 +175,19 @@ From `.env.example` and the Compose files, the variables relevant to the observa
- `GF_AUTH_GENERIC_OAUTH_API_URL`
### Alertmanager
- `SMTP_HOST` / `SMTP_PORT`
- `SMTP_USERNAME` / `SMTP_PASSWORD`
- `SMTP_FROM_ADDRESS`
- `ALERT_EMAIL_TO`
### Traefik / network (production)
- `BACKEND_APP_HOST` / `FRONTEND_APP_HOST` / `GRAFANA_APP_HOST`
- `CERT_RESOLVER` e.g. `letsencrypt`
### General
- `LOG_LEVEL` / `LOG_FORMAT` also passed to Grafana and backend.
## 3. Monitoring config files
@@ -193,7 +219,7 @@ Remote Node Exporter targets are not static: the backend reads machine settings
## 5. Setup steps and gotchas
- The observability stack is brought up with the app itself:
- Manage's own compose stack does **not** include observability services. To run a full local stack, bring up the app and the standalone observability example separately:
- Production: `docker compose -f docker-compose.yml up --build`
- Development: `docker compose -f docker-compose.dev.yml up --build`
- Production requires the external `web` network and Traefik already configured; `docker-compose.dev.yml` does not use Traefik and binds ports directly.
+14 -205
View File
@@ -1,3 +1,12 @@
# Manage development stack — backend + frontend only.
#
# Manage does NOT deploy its own Grafana/Prometheus/Loki/Alertmanager stack.
# It exposes a /metrics endpoint and optional Alertmanager proxy endpoints so
# an *existing* observability deployment can scrape/consume them.
#
# For a ready-to-use example observability stack, see
# docker-compose.observability.yml and docs/observability-runbooks.md.
services:
backend:
build:
@@ -15,7 +24,7 @@ services:
PROMETHEUS_ENABLED: "true"
SSH_KNOWN_HOSTS_PATH: /app/backend/.cache/known_hosts
PROMETHEUS_FILE_SD_DIR: /app/backend/.cache/prometheus-file-sd
ALERTMANAGER_URL: ${ALERTMANAGER_URL:-http://alertmanager:9093}
ALERTMANAGER_URL: ${ALERTMANAGER_URL:-}
ALERTMANAGER_WEBHOOK_URL: ${ALERTMANAGER_WEBHOOK_URL:-}
MANAGE_ENCRYPTION_KEY: ${MANAGE_ENCRYPTION_KEY:?set MANAGE_ENCRYPTION_KEY in your .env}
ports:
@@ -25,7 +34,6 @@ services:
- ${BACKEND_CACHE_DIR:-./backend-cache}:/app/backend/.cache
networks:
- web
- monitoring
restart: unless-stopped
frontend:
@@ -38,8 +46,8 @@ services:
VITE_API_URL: "/api"
VITE_OIDC_ENABLED: "false"
VITE_DEV_API_PROXY_TARGET: "http://backend:8000"
VITE_GRAFANA_URL: "http://localhost:3000"
VITE_PROMETHEUS_URL: "http://localhost:9090"
VITE_GRAFANA_URL: ${VITE_GRAFANA_URL:-http://localhost:3000}
VITE_PROMETHEUS_URL: ${VITE_PROMETHEUS_URL:-http://localhost:9090}
ports:
- "5173:5173"
volumes:
@@ -47,211 +55,12 @@ services:
- frontend_node_modules:/app/frontend/node_modules
depends_on:
- backend
restart: unless-stopped
prometheus:
image: prom/prometheus:v2.55.1
container_name: prometheus
command:
- "--config.file=/etc/prometheus/prometheus.yml"
- "--storage.tsdb.path=/prometheus"
- "--storage.tsdb.retention.time=30d"
- "--web.console.libraries=/usr/share/prometheus/console_libraries"
- "--web.console.templates=/usr/share/prometheus/consoles"
- "--web.enable-lifecycle"
volumes:
- ./monitoring/prometheus/prometheus.yml:/etc/prometheus/prometheus.yml:ro
- ./monitoring/prometheus/rules:/etc/prometheus/rules:ro
- ${BACKEND_CACHE_DIR:-./backend-cache}/prometheus-file-sd:/etc/prometheus/file-sd:ro
- prometheus_data:/prometheus
ports:
- "9090:9090"
networks:
- monitoring
- web
restart: unless-stopped
healthcheck:
test: ["CMD", "wget", "-qO-", "http://127.0.0.1:9090/-/healthy"]
interval: 30s
timeout: 5s
retries: 3
start_period: 30s
deploy:
resources:
limits:
cpus: "1.00"
memory: 1G
reservations:
cpus: "0.25"
memory: 256M
loki:
image: grafana/loki:3.1.1
container_name: loki
command: -config.file=/etc/loki/loki.yml
volumes:
- ./monitoring/loki/loki.yml:/etc/loki/loki.yml:ro
- loki_data:/loki
ports:
- "3100:3100"
networks:
- monitoring
restart: unless-stopped
healthcheck:
test: ["CMD", "wget", "-qO-", "http://127.0.0.1:3100/ready"]
interval: 30s
timeout: 5s
retries: 3
start_period: 30s
deploy:
resources:
limits:
cpus: "1.00"
memory: 1G
reservations:
cpus: "0.25"
memory: 256M
alloy:
image: grafana/alloy:v1.5.0
container_name: alloy
command:
- run
- /etc/alloy/config.alloy
- --storage.path=/var/lib/alloy
volumes:
- ./monitoring/alloy/config.alloy:/etc/alloy/config.alloy:ro
- /var/run/docker.sock:/var/run/docker.sock:ro
- /var/lib/docker/containers:/var/lib/docker/containers:ro
networks:
- monitoring
depends_on:
loki:
condition: service_healthy
restart: unless-stopped
user: root
healthcheck:
test: ["CMD", "wget", "-qO-", "http://127.0.0.1:12345/-/healthy"]
interval: 30s
timeout: 5s
retries: 3
start_period: 30s
deploy:
resources:
limits:
cpus: "0.50"
memory: 512M
reservations:
cpus: "0.10"
memory: 128M
grafana:
image: grafana/grafana:11.3.1
container_name: grafana
environment:
GF_SECURITY_ADMIN_USER: ${GRAFANA_ADMIN_USER:-admin}
GF_SECURITY_ADMIN_PASSWORD: ${GRAFANA_ADMIN_PASSWORD:-admin}
GF_AUTH_GENERIC_OAUTH_CLIENT_ID: ${GF_AUTH_GENERIC_OAUTH_CLIENT_ID:-}
GF_AUTH_GENERIC_OAUTH_CLIENT_SECRET: ${GF_AUTH_GENERIC_OAUTH_CLIENT_SECRET:-}
GF_AUTH_GENERIC_OAUTH_AUTH_URL: ${GF_AUTH_GENERIC_OAUTH_AUTH_URL:-}
GF_AUTH_GENERIC_OAUTH_TOKEN_URL: ${GF_AUTH_GENERIC_OAUTH_TOKEN_URL:-}
GF_AUTH_GENERIC_OAUTH_API_URL: ${GF_AUTH_GENERIC_OAUTH_API_URL:-}
LOG_LEVEL: ${LOG_LEVEL:-INFO}
volumes:
- ./monitoring/grafana/grafana.ini:/etc/grafana/grafana.ini:ro
- ./monitoring/grafana/provisioning:/etc/grafana/provisioning:ro
- grafana_data:/var/lib/grafana
ports:
- "3000:3000"
networks:
- monitoring
depends_on:
prometheus:
condition: service_healthy
loki:
condition: service_healthy
restart: unless-stopped
healthcheck:
test: ["CMD", "wget", "-qO-", "http://127.0.0.1:3000/api/health"]
interval: 30s
timeout: 5s
retries: 3
start_period: 30s
deploy:
resources:
limits:
cpus: "1.00"
memory: 512M
reservations:
cpus: "0.25"
memory: 128M
alertmanager:
image: prom/alertmanager:v0.27.0
container_name: alertmanager
command:
- "--config.file=/etc/alertmanager/alertmanager.yml"
- "--storage.path=/alertmanager"
environment:
SMTP_HOST: ${SMTP_HOST:-smtp.example.com}
SMTP_PORT: ${SMTP_PORT:-587}
SMTP_USERNAME: ${SMTP_USERNAME:-}
SMTP_PASSWORD: ${SMTP_PASSWORD:-}
SMTP_FROM_ADDRESS: ${SMTP_FROM_ADDRESS:-no-reply@example.com}
ALERT_EMAIL_TO: ${ALERT_EMAIL_TO:-admin@example.com}
volumes:
- ./monitoring/alertmanager/alertmanager.yml:/etc/alertmanager/alertmanager.yml:ro
- alertmanager_data:/alertmanager
ports:
- "9093:9093"
networks:
- monitoring
restart: unless-stopped
healthcheck:
test: ["CMD", "wget", "-qO-", "http://127.0.0.1:9093/-/healthy"]
interval: 30s
timeout: 5s
retries: 3
start_period: 30s
deploy:
resources:
limits:
cpus: "0.50"
memory: 256M
reservations:
cpus: "0.10"
memory: 64M
node-exporter:
image: prom/node-exporter:v1.8.2
container_name: node-exporter
command:
- "--path.rootfs=/host"
volumes:
- /:/host:ro,rslave
networks:
- monitoring
restart: unless-stopped
healthcheck:
test: ["CMD", "wget", "-qO-", "http://127.0.0.1:9100/"]
interval: 30s
timeout: 5s
retries: 3
start_period: 10s
deploy:
resources:
limits:
cpus: "0.25"
memory: 128M
reservations:
cpus: "0.05"
memory: 32M
networks:
monitoring:
web:
volumes:
frontend_node_modules:
prometheus_data:
loki_data:
grafana_data:
alertmanager_data:
+10 -1
View File
@@ -1,4 +1,13 @@
# Standalone observability stack.
# Standalone observability stack (OPTIONAL EXAMPLE).
#
# Manage itself does NOT deploy Grafana/Prometheus/Loki/Alertmanager/Alloy/Node
# Exporter. The root docker-compose.yml / docker-compose.dev.yml ship only the
# backend and frontend, and Manage connects to EXISTING Grafana/Prometheus/
# Alertmanager instances.
#
# This file is a ready-to-use example you can run on a host where you want the
# full Grafana, Prometheus, Loki, Alertmanager, Alloy and Node Exporter stack
# without the rest of Manage. It is not required to run Manage.
#
# Run this on a host where you want Grafana, Prometheus, Loki, Alertmanager,
# Alloy and Node Exporter without the rest of Manage.
+11 -215
View File
@@ -1,3 +1,12 @@
# Manage production stack — backend + frontend only.
#
# Manage does NOT deploy its own Grafana/Prometheus/Loki/Alertmanager stack.
# It exposes a /metrics endpoint and optional Alertmanager proxy endpoints so
# an *existing* observability deployment can scrape/consume them.
#
# For a ready-to-use example observability stack, see
# docker-compose.observability.yml and docs/observability-runbooks.md.
services:
backend:
build:
@@ -26,7 +35,7 @@ services:
SMTP_TIMEOUT: ${SMTP_TIMEOUT:-30}
SSH_KNOWN_HOSTS_PATH: /app/backend/.cache/known_hosts
PROMETHEUS_FILE_SD_DIR: ${PROMETHEUS_FILE_SD_DIR:-/app/backend/.cache/prometheus-file-sd}
ALERTMANAGER_URL: ${ALERTMANAGER_URL:-http://alertmanager:9093}
ALERTMANAGER_URL: ${ALERTMANAGER_URL:-}
ALERTMANAGER_WEBHOOK_URL: ${ALERTMANAGER_WEBHOOK_URL:-}
MANAGE_ENCRYPTION_KEY: ${MANAGE_ENCRYPTION_KEY:?generate one with python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"}
volumes:
@@ -34,7 +43,6 @@ services:
restart: unless-stopped
networks:
- web
- monitoring
expose:
- "8000"
labels:
@@ -71,7 +79,7 @@ services:
VITE_OIDC_POST_LOGOUT_REDIRECT_URI: ${VITE_OIDC_POST_LOGOUT_REDIRECT_URI:?set VITE_OIDC_POST_LOGOUT_REDIRECT_URI}
VITE_DEV_API_PROXY_TARGET: ${VITE_DEV_API_PROXY_TARGET:-http://backend:8000}
VITE_GRAFANA_URL: ${VITE_GRAFANA_URL:-https://grafana.example.com}
VITE_PROMETHEUS_URL: ${VITE_PROMETHEUS_URL:-http://localhost:9090}
VITE_PROMETHEUS_URL: ${VITE_PROMETHEUS_URL:-http://prometheus.example.com}
VITE_APP_VERSION: ${APP_VERSION:-0.1.0}
VITE_APP_BUILD_INFO: ${APP_BUILD_INFO:-dev}
depends_on:
@@ -89,218 +97,6 @@ services:
- "8080:80"
restart: unless-stopped
prometheus:
image: prom/prometheus:v2.55.1
container_name: prometheus
command:
- "--config.file=/etc/prometheus/prometheus.yml"
- "--storage.tsdb.path=/prometheus"
- "--storage.tsdb.retention.time=30d"
- "--web.console.libraries=/usr/share/prometheus/console_libraries"
- "--web.console.templates=/usr/share/prometheus/consoles"
- "--web.enable-lifecycle"
volumes:
- ./monitoring/prometheus/prometheus.yml:/etc/prometheus/prometheus.yml:ro
- ./monitoring/prometheus/rules:/etc/prometheus/rules:ro
- ${BACKEND_CACHE_DIR:-./backend-cache}/prometheus-file-sd:/etc/prometheus/file-sd:ro
- prometheus_data:/prometheus
expose:
- "9090"
networks:
- web
- monitoring
restart: unless-stopped
healthcheck:
test: ["CMD", "wget", "-qO-", "http://127.0.0.1:9090/-/healthy"]
interval: 30s
timeout: 5s
retries: 3
start_period: 30s
deploy:
resources:
limits:
cpus: "1.00"
memory: 1G
reservations:
cpus: "0.25"
memory: 256M
loki:
image: grafana/loki:3.1.1
container_name: loki
command: -config.file=/etc/loki/loki.yml
volumes:
- ./monitoring/loki/loki.yml:/etc/loki/loki.yml:ro
- loki_data:/loki
expose:
- "3100"
networks:
- monitoring
restart: unless-stopped
healthcheck:
test: ["CMD", "wget", "-qO-", "http://127.0.0.1:3100/ready"]
interval: 30s
timeout: 5s
retries: 3
start_period: 30s
deploy:
resources:
limits:
cpus: "1.00"
memory: 1G
reservations:
cpus: "0.25"
memory: 256M
alloy:
image: grafana/alloy:v1.5.0
container_name: alloy
command:
- run
- /etc/alloy/config.alloy
- --storage.path=/var/lib/alloy
volumes:
- ./monitoring/alloy/config.alloy:/etc/alloy/config.alloy:ro
- /var/run/docker.sock:/var/run/docker.sock:ro
- /var/lib/docker/containers:/var/lib/docker/containers:ro
networks:
- monitoring
depends_on:
loki:
condition: service_healthy
restart: unless-stopped
user: root
healthcheck:
test: ["CMD", "wget", "-qO-", "http://127.0.0.1:12345/-/healthy"]
interval: 30s
timeout: 5s
retries: 3
start_period: 30s
deploy:
resources:
limits:
cpus: "0.50"
memory: 512M
reservations:
cpus: "0.10"
memory: 128M
grafana:
image: grafana/grafana:11.3.1
container_name: grafana
environment:
GF_SECURITY_ADMIN_USER: ${GRAFANA_ADMIN_USER:-admin}
GF_SECURITY_ADMIN_PASSWORD: ${GRAFANA_ADMIN_PASSWORD:-admin}
GF_AUTH_GENERIC_OAUTH_CLIENT_ID: ${GF_AUTH_GENERIC_OAUTH_CLIENT_ID:-}
GF_AUTH_GENERIC_OAUTH_CLIENT_SECRET: ${GF_AUTH_GENERIC_OAUTH_CLIENT_SECRET:-}
GF_AUTH_GENERIC_OAUTH_AUTH_URL: ${GF_AUTH_GENERIC_OAUTH_AUTH_URL:-}
GF_AUTH_GENERIC_OAUTH_TOKEN_URL: ${GF_AUTH_GENERIC_OAUTH_TOKEN_URL:-}
GF_AUTH_GENERIC_OAUTH_API_URL: ${GF_AUTH_GENERIC_OAUTH_API_URL:-}
LOG_LEVEL: ${LOG_LEVEL:-INFO}
volumes:
- ./monitoring/grafana/grafana.ini:/etc/grafana/grafana.ini:ro
- ./monitoring/grafana/provisioning:/etc/grafana/provisioning:ro
- grafana_data:/var/lib/grafana
expose:
- "3000"
networks:
- web
- monitoring
depends_on:
prometheus:
condition: service_healthy
loki:
condition: service_healthy
restart: unless-stopped
healthcheck:
test: ["CMD", "wget", "-qO-", "http://127.0.0.1:3000/api/health"]
interval: 30s
timeout: 5s
retries: 3
start_period: 30s
labels:
- "traefik.enable=true"
- "traefik.http.routers.${GRAFANA_APP_NAME:-grafana}.rule=Host(`${GRAFANA_APP_HOST:?set GRAFANA_APP_HOST}`)"
- "traefik.http.routers.${GRAFANA_APP_NAME:-grafana}.entrypoints=websecure"
- "traefik.http.routers.${GRAFANA_APP_NAME:-grafana}.tls.certresolver=${CERT_RESOLVER:?set CERT_RESOLVER}"
- "traefik.http.services.${GRAFANA_APP_NAME:-grafana}.loadbalancer.server.port=${GRAFANA_APP_PORT:-3000}"
deploy:
resources:
limits:
cpus: "1.00"
memory: 512M
reservations:
cpus: "0.25"
memory: 128M
alertmanager:
image: prom/alertmanager:v0.27.0
container_name: alertmanager
command:
- "--config.file=/etc/alertmanager/alertmanager.yml"
- "--storage.path=/alertmanager"
environment:
SMTP_HOST: ${SMTP_HOST:-smtp.example.com}
SMTP_PORT: ${SMTP_PORT:-587}
SMTP_USERNAME: ${SMTP_USERNAME:-}
SMTP_PASSWORD: ${SMTP_PASSWORD:-}
SMTP_FROM_ADDRESS: ${SMTP_FROM_ADDRESS:-no-reply@example.com}
ALERT_EMAIL_TO: ${ALERT_EMAIL_TO:-admin@example.com}
volumes:
- ./monitoring/alertmanager/alertmanager.yml:/etc/alertmanager/alertmanager.yml:ro
- alertmanager_data:/alertmanager
expose:
- "9093"
networks:
- monitoring
restart: unless-stopped
healthcheck:
test: ["CMD", "wget", "-qO-", "http://127.0.0.1:9093/-/healthy"]
interval: 30s
timeout: 5s
retries: 3
start_period: 30s
deploy:
resources:
limits:
cpus: "0.50"
memory: 256M
reservations:
cpus: "0.10"
memory: 64M
node-exporter:
image: prom/node-exporter:v1.8.2
container_name: node-exporter
command:
- "--path.rootfs=/host"
volumes:
- /:/host:ro,rslave
networks:
- monitoring
restart: unless-stopped
healthcheck:
test: ["CMD", "wget", "-qO-", "http://127.0.0.1:9100/"]
interval: 30s
timeout: 5s
retries: 3
start_period: 10s
deploy:
resources:
limits:
cpus: "0.25"
memory: 128M
reservations:
cpus: "0.05"
memory: 32M
networks:
web:
external: true
monitoring:
volumes:
prometheus_data:
loki_data:
grafana_data:
alertmanager_data:
+1 -1
View File
@@ -92,7 +92,7 @@ repo/
│ └── types/
│ └── index.ts
├── docker-compose.yml # Optional unified deployment
├── docker-compose.yml # Backend + frontend deployment (observability is external)
└── README.md
```
+2 -1
View File
@@ -197,7 +197,7 @@ fully removed (web-ui-rework; see decision log 2026-06-17).
- Dashboard shortcuts should support a small icon/preview field so cards can be visually recognizable without changing the underlying model later.
- Support OIDC login in the frontend using an OIDC client library, with backend JWT validation for protected API requests.
- Persist frontend OIDC auth state across tab reloads by storing the OIDC user and request state in browser localStorage.
- Provide Docker Compose deployment files at the repository root for production and local development.
- Provide Docker Compose deployment files at the repository root for production and local development. These deploy **only** the backend and frontend; Manage connects to *existing* Grafana/Prometheus/Alertmanager instances and never ships its own observability stack (see `docker-compose.observability.yml` for an optional standalone example).
- SSH private keys should be managed as reusable saved secrets in Settings, independent of any one machine, and SSH machines should select from that saved-key list.
- The web UI should allow both importing an existing private key and generating a new SSH keypair for that saved-key list.
- Saved SSH keys should display their derived public key, fingerprint, and machine usage count so administrators can audit them at a glance.
@@ -331,6 +331,7 @@ the widget/addon-pages model were removed. `MANAGE_ENCRYPTION_KEY` is now requir
## Decision Log
- 2026-06-23: Removed all observability services from the root Compose files. `docker-compose.yml` and `docker-compose.dev.yml` now deploy **only** the backend and frontend; the `monitoring` network and the `prometheus`/`loki`/`alloy`/`grafana`/`alertmanager`/`node-exporter` services and their named volumes were deleted, and the `GRAFANA_APP_HOST` Traefik rule was removed. Manage connects to **existing** Grafana/Prometheus/Alertmanager instances and does not deploy them itself. The backend `alertmanager_url` default is now empty, and the `/api/monitoring/alerts` and `/alertmanager-status` endpoints return graceful "not configured" responses when `ALERTMANAGER_URL` is unset. The previous in-compose stack is preserved as an optional standalone example in `docker-compose.observability.yml` (config under `monitoring/`, documented in `docs/observability-runbooks.md`). `VITE_GRAFANA_URL`/`VITE_PROMETHEUS_URL` remain as optional frontend deep-link overrides.
- 2026-06-17: Decommissioned the legacy Manage-side system-metric scraping. Removed the backend `MonitoringPoller` (SSH-ran `df` on every machine every 5 min into a local SQLite `monitoring_machine_actions` table), the entire `services/monitoring_actions.py` module, the `/api/monitoring/poller`, `/api/monitoring/machines/{id}/actions`, and `/api/monitoring/disk` endpoints, the `monitoring_machine_actions` table (DROP on startup), the three `monitoring_poll_*` / `monitoring_action_retention_days` config knobs, and the orphaned frontend `DiskSpaceCard` + `DiskSpace` type. System metrics are now owned exclusively by Prometheus + node_exporter + Grafana. Kept the Alertmanager proxy (`/alerts`, `/alertmanager-status`, `/alertmanager-webhook`), `/prometheus-targets`, `/machines`, the `node_exporter_*` machine fields, and the on-demand `disk_usage` job template.
- 2026-06-17: Completed the web UI rework to a single design system. The frontend now uses **shadcn/ui + Tailwind CSS v4 + lucide-react** exclusively, with CSS `@theme` tokens in `src/index.css` (primary `#4f8cff`; `chart-1..5` repurposed as status/Grafana-link cues). Removed `@mui/material`, `@mui/icons-material`, `@mui/x-data-grid`, `@emotion/react`, `@emotion/styled`, `recharts`, `d3`, and the `src/theme.ts` shim. Tables moved from `@mui/x-data-grid`/AG Grid to a visibility-only TanStack `DataTable` wrapper (pagination, row selection, row click, column visibility — no sorting/resizing). Adopted the thin-dashboard observability model (no in-app charts; Alertmanager alerts + Prometheus target health + Grafana deep-links). Reconciled the information architecture: Backups is a top-level nav item at `/backups`, and the media surface is named Media at `/media` with `/applications` redirecting to `/media` (mirroring `/monitoring``/observability`). Frontend tests moved to Vitest + @testing-library/react (`npm test`), with legacy node suites in `frontend/tests`.
- 2026-06-13: Adopted a dedicated, self-hosted observability subsystem based on Prometheus, Grafana Loki, Grafana, and Alertmanager. Metrics will be pulled from Node Exporter on machines and from application exporters in containers; logs will be structured JSON shipped by Promtail/Grafana Alloy. The existing POSIX remote collector will be removed and backup alerts migrated to Alertmanager rules. See `docs/monitoring-logging-design.md`.
+11
View File
@@ -1,5 +1,16 @@
# Monitoring and Logging Design — Manage
> **Status (2026-06-23):** This document is the **reference architecture** for the
> self-hosted observability stack Manage integrates with. Manage itself **does
> not deploy** Grafana, Prometheus, Loki, Alertmanager, Alloy, or Node Exporter.
> The root `docker-compose.yml` / `docker-compose.dev.yml` ship **only** the
> backend and frontend; Manage connects to **existing** Grafana / Prometheus /
> Alertmanager instances. The stack described here is available as an optional,
> deploy-it-yourself example in `docker-compose.observability.yml` (see
> `docs/observability-runbooks.md`). The "Add services to `docker-compose.yml`"
> phase notes below describe the **original** in-compose deployment, which has
> since been extracted to the standalone compose file.
## Executive Summary
Manage currently uses ad-hoc observability: plain-text Python logs, a custom POSIX shell metrics collector on remote machines, and a background poller that stores snapshots in SQLite. This works for a single-instance homelab but becomes painful as the fleet grows and as users need faster incident response.
+5 -1
View File
@@ -1,6 +1,10 @@
# Observability Runbooks
Operational playbooks for the Manage self-hosted observability stack (Prometheus, Grafana, Loki, Alertmanager).
Operational playbooks for the **standalone example observability stack**
(`docker-compose.observability.yml`) that can be deployed alongside Manage.
Manage itself does **not** deploy these services; it connects to existing
Grafana / Prometheus / Alertmanager instances. These runbooks cover operating
the standalone stack shipped under `monitoring/`.
## Service Overview
+9 -10
View File
@@ -8,10 +8,9 @@ React + TypeScript SPA for Manage, consuming the FastAPI backend.
- **React 18+** — UI framework
- **TypeScript** — Type safety
- **@tanstack/react-query** — Data fetching/caching
- **ag-grid-react** — Data tables (media, file browser)
- **recharts** — Monitoring charts
- **@tanstack/react-table** — Data tables (media, file browser)
- **react-router-dom** — Client-side routing
- **Tailwind CSS** — Styling
- **Tailwind CSS** + **shadcn/ui** — Styling
## Setup
@@ -26,7 +25,7 @@ npm install
npm run dev
```
Runs on http://localhost:5173 with API requests proxied to http://localhost:8000.
Runs on <http://localhost:5173> with API requests proxied to <http://localhost:8000>.
Make sure the backend is running:
@@ -45,12 +44,13 @@ Output goes to `frontend/dist/`.
## Pages
- **Dashboard** (`/`) — Now playing, backend-collected per-machine monitoring table with 10-minute averages/min/max, library stats, frontend/backend version chips in the shell header
- **Monitoring** (`/monitoring`) — Per-machine CPU/IO wait/RAM/network/disk charts, collector controls, and backend-collected recent action history
- **Dashboard** (`/`) — Now playing, library stats, configurable widgets and shortcuts, frontend/backend version chips in the shell header
- **Observability** (`/observability`) — Thin dashboard: Alertmanager alerts, Prometheus target health, machine status, and Grafana deep-links (no in-app charting)
- **Media** (`/media`) — Full-library table with sort/filter/search
- **Users** (`/users`) — Read-only Jellyfin user list with optional Jellyseerr enrichment
- **File Browser** (`/files`) — Remote directory browsing, ffprobe preview, jobs
- **Settings** (`/settings`) — Persistent monitoring machine definitions and setup workflow
- **Settings** (`/settings`) — Persistent monitoring machine definitions, SSH keys, and setup workflow
- **Actions** (`/actions`) — Saved server tasks (shell/python) targeting ssh_tasks services
## Environment Variables
@@ -65,7 +65,6 @@ VITE_API_URL=http://your-backend-host:8000
- **Local development**: run `docker compose -f docker-compose.dev.yml up --build`, then open the app and add monitoring machines in the **Settings** tab.
- **Production**: export the required Compose variables in your shell, run `docker compose up --build`, and manage local/remote machines from **Settings**.
- **Dashboard monitoring UI**: the dashboard shows a compact, sortable table with one row per configured machine plus poller status.
- **Monitoring UI**: the **Monitoring** tab shows one card per configured machine, including a recent action-history table populated by the backend poller. A machine can be `local` (the API host itself) or `ssh` (a remote host), and the UI treats both the same after configuration. The page also shows the backend poller health badge.
- **Observability**: Manage only deploys backend + frontend. It connects to **existing** Grafana/Prometheus/Alertmanager instances; see `docker-compose.observability.yml` for an optional standalone example stack. A machine can be `local` (the API host itself) or `ssh` (a remote host), and the UI treats both the same after configuration.
In development, the Vite proxy handles `/api` requests automatically.
In development, the Vite proxy handles `/api` requests automatically. `VITE_GRAFANA_URL` / `VITE_PROMETHEUS_URL` are optional frontend deep-link overrides for your existing instances.
-48
View File
@@ -1,48 +0,0 @@
global:
scrape_interval: 15s
evaluation_interval: 15s
external_labels:
monitor: manage
alerting:
alertmanagers:
- static_configs:
- targets:
- alertmanager:9093
rule_files:
- /etc/prometheus/rules/*.yml
scrape_configs:
- job_name: prometheus
static_configs:
- targets:
- localhost:9090
- job_name: manage-backend
static_configs:
- targets:
- backend:8000
metrics_path: /metrics
scrape_interval: 15s
- job_name: node-exporter
static_configs:
- targets:
- node-exporter:9100
- job_name: loki
static_configs:
- targets:
- loki:3100
- job_name: alertmanager
static_configs:
- targets:
- alertmanager:9093
- job_name: node-exporter-remote
file_sd_configs:
- files:
- /etc/prometheus/file-sd/node_exporter_targets.json
refresh_interval: 30s