fix: harden agents, alerting, status page and deployment; align the docs with the code

.env.example

@@ -1,18 +1,26 @@
 # maintenant Configuration
 # ========================
 
-# Operating mode: embedded (default, server + local runtime), server (accepts
-# remote agents), or agent (reports to a server, no HTTP interface).
+# Operating mode: embedded (default: web server and local runtime, which also
+# accepts remote agents when the edition allows it), server (the same, but it
+# refuses to start below the Personal edition), or agent (reports to a server,
+# no HTTP interface).
 # MAINTENANT_MODE=embedded
 
 # Listen address (use 0.0.0.0 inside containers, 127.0.0.1 on host)
 MAINTENANT_ADDR=127.0.0.1:8080
+
+# Agent gRPC listener (server and embedded modes, Personal edition or above).
+# Loopback by default: remote agents cannot connect until you change it. In a
+# container use 0.0.0.0:8443 and publish the port.
 MAINTENANT_GRPC_LISTEN=127.0.0.1:8443
 
 # Log verbosity: debug, info (default), warn, error
 # MAINTENANT_LOG_LEVEL=info
 
-# SQLite database path
+# SQLite database path. The container image sets /data/maintenant.db. Its
+# directory also holds the license cache, the telemetry identity and the
+# embedded agent's data, even when the database itself is PostgreSQL.
 MAINTENANT_DB=./maintenant.db
 # Optional: back the server data set with a PostgreSQL you already operate.
 # Empty means SQLite, which is the default and the only agent storage.
@@ -22,12 +30,18 @@ MAINTENANT_DB=./maintenant.db
 # Organisation name (displayed on the public status page)
 # MAINTENANT_ORGANISATION_NAME=Acme Corp
 
-# Public base URL (used for heartbeat ping URLs and subscriber links)
+# Public base URL (heartbeat ping URLs, status page email links and the MCP
+# OAuth issuer). Default: http://<MAINTENANT_ADDR>
 # MAINTENANT_BASE_URL=https://maintenant.example.com
+# gRPC URL shown to agents in the enrollment commands (default: derived from
+# the Host of the web request)
 # MAINTENANT_GRPC_URL=grpcs://maintenant-agents.example.com
-# MAINTENANT_STATUS_URL=https://status.example.com (public)
+# Canonical URL of the status page: reported as status_url by GET /api/v1/edition
+# and opened by the admin link (default: the relative /status)
+# MAINTENANT_STATUS_URL=https://status.example.com
 
-# CORS allowed origins (comma-separated, empty = same-origin only)
+# Origins allowed to call the API cross-origin and to send state-changing
+# requests from a browser (comma-separated, empty = same-origin only)
 # MAINTENANT_CORS_ORIGINS=http://localhost:5173
 
 # Reverse proxies whose X-Forwarded-For / X-Real-IP / X-Forwarded-Host headers are
@@ -41,7 +55,8 @@ MAINTENANT_DB=./maintenant.db
 # Create HTTP endpoints from Traefik and Caddy docker-proxy container labels (Docker only)
 # MAINTENANT_PROXY_LABELS=true
 
-# Max request body size in bytes (default: 1MB)
+# Max request body size in bytes (default: 1048576). A value that is not a
+# positive whole number stops the startup.
 # MAINTENANT_MAX_BODY_SIZE=1048576
 
 # Update intelligence scan interval (Go duration, default: 24h)
@@ -52,12 +67,13 @@ MAINTENANT_DB=./maintenant.db
 
 # Raise an alert when a container has been stopped for this long (Go duration,
 # e.g. 5m). Unset or 0 disables the check; a container that exited with code 0
-# counts as finished, not down. The alert resolves on its own once it runs again.
+# or 143 (or 137 when the out-of-memory killer was not the cause) counts as
+# completed, not down. The alert resolves on its own once it runs again.
 # MAINTENANT_CONTAINER_DOWN_AFTER=5m
 
 # How long raw resource samples are kept (Go duration, default: 48h).
-# The 24h chart is the longest range reading them — 7d is served from the hourly
-# rollup — so 24h is the floor. Raw samples dominate database size.
+# The 24h chart is the longest range reading them (7d is served from the hourly
+# rollup), so 24h is the floor. Raw samples dominate database size.
 # MAINTENANT_RETENTION_SNAPSHOTS=48h
 
 # Time between two retention passes (Go duration, default: 1h, minimum 1m)
@@ -66,51 +82,69 @@ MAINTENANT_DB=./maintenant.db
 # Rows deleted per transaction during retention (default: 1000, range 100-100000)
 # MAINTENANT_RETENTION_BATCH_SIZE=1000
 
-# Score below which the security posture raises an alert (unset = no alert)
+# Score below which the security posture raises an alert, from 1 to 100,
+# checked every 5 minutes (Personal edition; unset or 0 = no alert, a value outside 0-100 or
+# not a number stops the startup)
 # MAINTENANT_SECURITY_SCORE_THRESHOLD=70
 
 # Opt out of anonymous usage telemetry
 # MAINTENANT_DISABLE_TELEMETRY=true
 
-# Allow notification webhooks pointing at private addresses (SSRF guard off).
-# Only on a network where you trust every webhook target.
+# Development only: allow http:// and private, loopback or link-local targets
+# for notification channels and webhook subscriptions (SSRF guard off).
+# Only on a network where you trust every target.
 # MAINTENANT_ALLOW_PRIVATE_WEBHOOKS=true
 
-# Kubernetes namespaces to monitor (comma-separated, empty = all)
+# Kubernetes namespaces to monitor (comma-separated, empty = all except
+# kube-system, kube-public and kube-node-lease)
 # MAINTENANT_K8S_NAMESPACES=default,production
 
-# Kubernetes namespaces to exclude (comma-separated)
-# MAINTENANT_K8S_EXCLUDE_NAMESPACES=kube-system
+# Kubernetes namespaces to exclude (comma-separated, added to the three above;
+# ignored when an allowlist is set)
+# MAINTENANT_K8S_EXCLUDE_NAMESPACES=monitoring
 
-# Pro license key (enables Pro features)
+# Personal or Pro license key
 # MAINTENANT_LICENSE_KEY=your-license-key
 
+# GitHub token used when fetching release notes for the changelog (Personal
+# edition). Optional: it only raises the GitHub API rate limit.
+# GITHUB_TOKEN=ghp_xxx
+
 # MCP Server (Model Context Protocol for AI assistants)
 # Both credentials are required: /mcp bypasses the reverse-proxy auth, so
 # without them maintenant refuses to start rather than serving your monitoring
 # data to anyone. Set MAINTENANT_MCP_ALLOW_UNAUTHENTICATED=true to accept that
-# on a trusted network.
+# on a trusted network. Use a secret of at least 32 characters
+# (openssl rand -hex 32).
 # MAINTENANT_MCP=true
 # MAINTENANT_MCP_CLIENT_ID=maintenant-mcp
 # MAINTENANT_MCP_CLIENT_SECRET=your-secret-here
+# Loopback redirect URIs are always accepted; list the others exactly.
 # MAINTENANT_MCP_ALLOWED_REDIRECT_URIS=https://claude.ai/api/mcp/auth_callback
 # MAINTENANT_MCP_ALLOW_UNAUTHENTICATED=true
 
-# SMTP configuration (required for email notification channels)
+# SMTP configuration (email alert channel with Personal, status page
+# subscribers with Pro). Port 465 uses implicit TLS; on other ports STARTTLS is
+# used when the server announces it.
 # MAINTENANT_SMTP_HOST=smtp.example.com
 # MAINTENANT_SMTP_PORT=587
 # MAINTENANT_SMTP_USERNAME=alerts@example.com
 # MAINTENANT_SMTP_PASSWORD=secret
 # MAINTENANT_SMTP_FROM=maintenant@example.com
 
 # Extra root CA to trust, for hosts signed by an internal PKI (step-ca, AD CS...).
-# Added to the system roots, never replacing them. Mount it readable by uid 65534.
+# Added to the system roots, never replacing them. Applies to endpoint and
+# certificate checks, webhooks and channels, outbound heartbeats, SMTP, the
+# license server, registries and the agent's connection to its server. Mount it
+# readable by uid 65534; an unreadable file stops the startup.
 # Prefer this over SSL_CERT_FILE, which replaces the whole bundle and fails silently.
 # MAINTENANT_CA_CERT=/etc/maintenant/ca.pem
 
 # ── Multi-host ────────────────────────────────────────────────────────────────
-# An agent needs the server URL and, on first boot only, an enrollment token.
-# The token is consumed once; the agent then authenticates with its own key.
+# An agent needs the server URL and, on first boot, an enrollment token. The
+# token is consumed once; the agent then authenticates with its own key. If the
+# server refuses the stored identity (agent revoked or deleted), the agent
+# enrolls again with the token when it is still set, and stops otherwise.
 # MAINTENANT_SERVER=grpcs://maintenant-agents.example.com:8443
 # MAINTENANT_ENROLLMENT_TOKEN=paste-the-token-from-the-Agents-page
 # MAINTENANT_LABEL=web-01
@@ -119,14 +153,17 @@ MAINTENANT_DB=./maintenant.db
 # operating system. Left empty, the agent finds it from its own pod.
 # MAINTENANT_NODE_NAME=node-01
 
-# Where the agent keeps its identity and liveness files (agent mode)
+# Where the agent keeps its identity, its spool database and its liveness file
+# (agent mode)
 # MAINTENANT_DATA_DIR=/var/lib/maintenant
 
 # Skip TLS verification when reaching the server. Debug only: it defeats the
 # point of TLS. Use MAINTENANT_CA_CERT for an internal PKI instead.
 # MAINTENANT_GRPC_INSECURE_SKIP_TLS_VERIFY=true
 
-# Server side: TLS for the gRPC listener agents connect to.
+# Server side: TLS for the gRPC listener agents connect to. Set both or neither:
+# one without the other stops the startup. With neither, a self-signed
+# certificate is generated at each start and a warning is logged.
 # MAINTENANT_GRPC_TLS_CERT=/etc/maintenant/grpc.crt
 # MAINTENANT_GRPC_TLS_KEY=/etc/maintenant/grpc.key
 # Serve gRPC as h2c instead, without TLS. Only behind a reverse proxy that
@@ -139,10 +176,11 @@ MAINTENANT_DB=./maintenant.db
 # MAINTENANT_AGENT_STALE_THRESHOLD_SECONDS=60
 
 # Agent side: local queue holding events while the server is unreachable.
-# Setting both budgets to 0 disables it.
+# Setting both the memory and the disk budget to 0 disables it. Events older
+# than the age limit are dropped from it; 0 turns the limit off.
 # MAINTENANT_AGENT_SPOOL_MAX_MEMORY_BYTES=16777216
 # MAINTENANT_AGENT_SPOOL_MAX_DISK_BYTES=134217728
 # MAINTENANT_AGENT_SPOOL_MAX_AGE_SECONDS=86400
 
-# Also run a local agent alongside the server (server mode, Pro)
+# Also run a local agent alongside the server (server mode, Personal edition or above)
 # MAINTENANT_EMBEDDED_AGENT=true

Dockerfile

@@ -42,7 +42,8 @@ RUN --mount=type=cache,target=/go/pkg/mod \
 
 FROM alpine:3.21
 
-RUN apk add --no-cache ca-certificates tzdata setpriv \
+RUN apk upgrade --no-cache \
+    && apk add --no-cache ca-certificates tzdata setpriv \
     && mkdir -p /data \
     && chown 65534:65534 /data
 
@@ -51,6 +52,9 @@ RUN apk add --no-cache ca-certificates tzdata setpriv \
 # /tmp as a tiny tmpfs, which SQLITE_FULL-fails the conversion; /data has real space.
 ENV SQLITE_TMPDIR=/data
 
+# Its directory also holds the licence cache and the update window, PostgreSQL or not.
+ENV MAINTENANT_DB=/data/maintenant.db
+
 # Tells the OS identity reader it must not fall back to the image's own
 # /etc/os-release, which describes the container rather than the host.
 ENV MAINTENANT_CONTAINER=1