feat: add optional resource metrics (Prometheus, cAdvisor, node-exporter)

Add 3 metrics services behind Docker Compose profiles (off by default).
Enable with ENABLE_METRICS=true on bootstrap or COMPOSE_PROFILES=metrics
in .env. Includes Prometheus config, Grafana datasource, and a 12-panel
Resource Metrics dashboard. Configs are written unconditionally so
enabling later doesn't require re-bootstrap.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: baijum

docs/server-contract.md

@@ -6,8 +6,8 @@ This document defines the contract between the platform infrastructure (bootstra
 
 ```
 /opt/platform/                          # Platform root (created by bootstrap-server.sh)
-  docker-compose.yml                    # Platform services (postgres, redis, minio, caddy, loki, promtail, grafana)
-  .env                                  # Platform credentials (POSTGRES_PASSWORD, MINIO_ROOT_*, GRAFANA_ADMIN_PASSWORD, ACME_EMAIL, OPS_DOMAIN, ALERT_REPO)
+  docker-compose.yml                    # Platform services (7 core + 3 optional metrics)
+  .env                                  # Platform credentials (POSTGRES_PASSWORD, MINIO_ROOT_*, GRAFANA_ADMIN_PASSWORD, ACME_EMAIL, OPS_DOMAIN, ALERT_REPO, COMPOSE_PROFILES)
   .bootstrapped                         # Timestamp marker from last bootstrap run
   Caddyfile                             # Global Caddyfile — imports /etc/caddy/apps/*.caddy
   caddy-apps/                           # Per-app Caddyfile fragments (written by deploy/preview workflows)
@@ -25,6 +25,7 @@ This document defines the contract between the platform infrastructure (bootstra
     usage-report.sh
   loki-config.yml                       # Loki configuration
   promtail-config.yml                   # Promtail configuration
+  prometheus.yml                        # Prometheus scrape config (always created)
   grafana/                              # Grafana provisioning files and dashboards
     provisioning/datasources/
     provisioning/dashboards/
@@ -45,12 +46,13 @@ This document defines the contract between the platform infrastructure (bootstra
   caddy/config/                         # Caddy config state
   loki/                                 # Loki log storage
   grafana/                              # Grafana state
+  prometheus/                           # Prometheus data (created always, used when metrics enabled)
   backups/postgres/                     # pg_dump backup files (7-day retention)
 ```
 
 ## Bootstrap to Deploy Lifecycle
 
-1. **Bootstrap the server** — Run `sudo bash infrastructure/bootstrap-server.sh` on a fresh Debian machine. This creates the directory layout above, installs Docker, creates the `deploy` user, generates platform credentials, starts the 7 platform services, copies infrastructure scripts, and installs cron jobs.
+1. **Bootstrap the server** — Run `sudo bash infrastructure/bootstrap-server.sh` on a fresh Debian machine. This creates the directory layout above, installs Docker, creates the `deploy` user, generates platform credentials, starts the 7 core platform services (plus 3 optional metrics services if enabled), copies infrastructure scripts, and installs cron jobs.
 
 2. **Configure DNS** — Point app domains and `*.preview.<domain>` to the server IP.
 
@@ -115,7 +117,7 @@ The bootstrap script applies several security measures automatically. Self-hoste
 
 **Credential isolation** — The platform `.env` file is mode 600 (readable only by its owner). Per-app credentials are generated by `create-app-credentials.sh` and stored in separate files under `/opt/platform/credentials/`, each also mode 600.
 
-**Container resource limits** — Every platform service and every app container has explicit CPU and memory limits in its Docker Compose file. This prevents any single container from exhausting server resources.
+**Container resource limits** — Every platform service and every app container has explicit CPU and memory limits in its Docker Compose file. This prevents any single container from exhausting server resources. The 7 core services use ~2.66G / 3.25 CPU. The 3 optional metrics services add 448M / 1.00 CPU when enabled.
 
 **Mandatory Access Control (AppArmor)** — Debian 12 ships with AppArmor enabled by default. Docker automatically applies the `docker-default` AppArmor profile to all containers, which restricts capabilities like writing to `/proc` and `/sys`, mounting filesystems, and accessing raw sockets. No configuration is needed — this works out of the box.
 
@@ -194,3 +196,26 @@ fi
 ```
 
 If no credentials file exists, the workflow falls back to whatever is already in `deploy/.env` and logs a warning.
+
+## Resource Metrics (Optional)
+
+Three additional services provide real-time resource visibility in Grafana. They are **off by default** and use Docker Compose profiles to control startup.
+
+| Service | Image | Memory Limit | CPU Limit | Purpose |
+|---|---|---|---|---|
+| prometheus | prom/prometheus:v2.53.0 | 256M | 0.50 | Metrics storage and queries |
+| cadvisor | gcr.io/cadvisor/cadvisor:v0.49.1 | 128M | 0.25 | Container metrics |
+| node-exporter | prom/node-exporter:v1.8.1 | 64M | 0.25 | Host metrics |
+
+**To enable** — add `COMPOSE_PROFILES=metrics` to `/opt/platform/.env`, then run `docker compose up -d` in `/opt/platform/`. Or bootstrap with `sudo ENABLE_METRICS=true bash bootstrap-server.sh`.
+
+**To disable** — remove the `COMPOSE_PROFILES=metrics` line from `.env`, then stop the metrics services with `docker compose --profile metrics down`.
+
+The Prometheus config (`/opt/platform/prometheus.yml`), Grafana datasource, and dashboard JSON are always created during bootstrap — they are harmless without running services and avoid needing to re-bootstrap to enable metrics later. Only the service startup is conditional.
+
+The "Resource Metrics" dashboard in Grafana includes:
+
+- **Host overview**: CPU %, memory %, disk %, uptime (stat panels)
+- **Host time series**: CPU, memory, disk I/O, network I/O over time
+- **Container overview**: table of all containers with CPU, memory, network
+- **Per-container detail**: filterable CPU and memory time series per container