release: 0.3.0: production hardening and checks that prove the data paths

.env.example

@@ -1,22 +1,49 @@
 # Copy to .env and fill in. The .env file is gitignored.
 
+# Which compose overlays this host runs; every `just` recipe acts on the same
+# set. Unset = the core stack only.
+#   production:  COMPOSE_FILE=compose.yml:compose.tunnel.yml
+#   local demo:  COMPOSE_FILE=compose.yml:compose.demo.yml
+#COMPOSE_FILE=
+
 GRAFANA_ADMIN_PASSWORD=change-me
 
 # Set to the public URL Cloudflare Tunnel exposes Grafana on, e.g.:
 #   GRAFANA_ROOT_URL=https://grafana.example.com
 GRAFANA_ROOT_URL=http://localhost:3000
 
+# Set to true whenever GRAFANA_ROOT_URL is https; `just up` with the tunnel
+# overlay refuses to run without it. Keep false for plain-http localhost use,
+# or logins break.
+GRAFANA_COOKIE_SECURE=false
+
 # Bearer token every telemetry sender must present (Authorization: Bearer <token>).
-# The default only suits local use — generate a real one for production, e.g.: openssl rand -hex 32
+# The default only suits local use. Generate a real one for production:
+# openssl rand -hex 32
 OTLP_AUTH_TOKEN=local-dev-token
 
-# Where Alertmanager delivers alert notifications (any webhook: ntfy, Slack, …).
-# Leave empty to run without delivery; failures are logged and harmless.
+# Where Grafana delivers alert notifications (any webhook: ntfy, Slack, …).
+# Not optional: an empty value drops every alert silently while the heartbeat
+# below keeps reporting healthy. With the tunnel overlay active, `just up`
+# refuses to start without it.
 ALERT_WEBHOOK_URL=
+
 # Dead man's switch ping target (e.g. https://hc-ping.com/<uuid>). The Watchdog
 # alert posts here every 5m; alert externally when pings stop.
 HEARTBEAT_URL=
 
-# Only needed for `just up-tunnel` (production exposure via Cloudflare Tunnel).
-# From: Cloudflare Zero Trust → Networks → Tunnels → <your tunnel> → Configure → token
+# Optional. Lets `./bootstrap.sh` create a project's healthchecks.io checks.
+# Must be the project's READ-WRITE API key (Project Settings -> API keys).
+HEALTHCHECKS_API_KEY=
+
+# Only needed with the tunnel overlay: cd infra && tofu output -raw tunnel_token
 CLOUDFLARE_TUNNEL_TOKEN=
+
+# Set to true to let Cloudflare Access sign users into Grafana individually.
+# Needs both values below; `just up` with the tunnel overlay enforces that.
+GRAFANA_JWT_AUTH=false
+# Your Zero Trust team name, the <team> in https://<team>.cloudflareaccess.com:
+# cd infra && tofu output -raw grafana_access_team_domain
+CF_ACCESS_TEAM_DOMAIN=
+# The Grafana Access application's aud tag: cd infra && tofu output -raw grafana_access_aud
+CF_ACCESS_AUD=

.github/dependabot.yml

@@ -1,23 +1,52 @@
 version: 2
 updates:
+  # Hub images: patch bumps ride together; a minor or major comes on its own,
+  # so a red PR names the one image that broke.
   - package-ecosystem: "docker-compose"
     directory: "/"
     schedule:
       interval: "weekly"
     groups:
-      monitoring-stack-updates:
-        patterns:
-          - "*"
+      hub-patches:
+        update-types: ["patch"]
 
+  # The spoke images every project host runs.
+  - package-ecosystem: "docker-compose"
+    directory: "/templates"
+    schedule:
+      interval: "weekly"
+    groups:
+      spoke-patches:
+        update-types: ["patch"]
+
+  # The demo: one PR per month for all of it.
   - package-ecosystem: "docker"
     directory: "/demo"
     schedule:
       interval: "monthly"
+    groups:
+      demo:
+        patterns: ["*"]
 
   - package-ecosystem: "pip"
     directory: "/demo"
     schedule:
       interval: "monthly"
+    groups:
+      demo:
+        patterns: ["*"]
+      # `groups` only cover version updates; without this every advisory opens
+      # its own PR. Only pip gets Dependabot security advisories here.
+      demo-security:
+        applies-to: security-updates
+        patterns: ["*"]
+
+  # Cloudflare provider for infra/. Dependabot bumps the constraint in
+  # main.tf but not the hashes in .terraform.lock.hcl; see the runbook.
+  - package-ecosystem: "terraform"
+    directory: "/infra"
+    schedule:
+      interval: "monthly"
 
   - package-ecosystem: "github-actions"
     directory: "/"

.github/workflows/ci.yml

@@ -1,29 +1,51 @@
-# Thin wrapper around the `just` contract: everything CI runs, you can run
-# locally with the same command.
+# Everything CI runs, you can run locally with the same `just` command. `lint`
+# has its own job so a lint failure reports without pulling the stack images.
 name: CI
 
+# Pull requests only: main moves through PRs, so a push run would repeat the
+# check. No path filter: gitleaks must see every PR, and a skipped workflow
+# never reports the checks a PR needs. infra/ also has its own (infra.yml).
 on:
-  push:
-    branches: [main]
   pull_request:
+  workflow_dispatch:
 
 permissions:
   contents: read
 
+# A push to an open PR supersedes the run in flight.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
-  check:
+  lint:
     runs-on: ubuntu-latest
+    timeout-minutes: 10
     steps:
-      - uses: actions/checkout@v7
-      - uses: extractions/setup-just@v4
-      - run: cp .env.example .env
-      - run: just check
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        # gitleaks scans git history; a shallow clone would pass vacuously.
+        with:
+          fetch-depth: 0
+      - uses: extractions/setup-just@53165ef7e734c5c07cb06b3c8e7b647c5aa16db3 # v4.0.0
+      # 600, or the exposure guards refuse it as world-readable.
+      - run: install -m 600 .env.example .env
+      - run: just lint
 
   smoke:
     runs-on: ubuntu-latest
+    timeout-minutes: 15
     steps:
-      - uses: actions/checkout@v7
-      - uses: extractions/setup-just@v4
-      - run: cp .env.example .env
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: extractions/setup-just@53165ef7e734c5c07cb06b3c8e7b647c5aa16db3 # v4.0.0
+      # 600, or the exposure guards refuse it as world-readable.
+      - run: install -m 600 .env.example .env
+      - run: just validate
+      # SMOKE_ALERTS adds the TargetDown round trip (about 3 minutes).
       - run: just smoke
-      - run: just down
+        env:
+          SMOKE_ALERTS: "1"
+      # The smoke failure messages point at these logs.
+      - if: failure()
+        run: just smoke-logs
+      - if: always()
+        run: just smoke-down

.github/workflows/infra.yml

@@ -0,0 +1,25 @@
+# OpenTofu validation for infra/, on its own trigger: it downloads the
+# provider every run and nothing outside infra/ can change its result.
+name: infra
+
+on:
+  pull_request:
+    paths: ["infra/**"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: extractions/setup-just@53165ef7e734c5c07cb06b3c8e7b647c5aa16db3 # v4.0.0
+      - run: install -m 600 .env.example .env # 600 or the exposure guards reject it
+      - run: just infra-validate

.gitignore

@@ -4,5 +4,6 @@
 backups/
 infra/.terraform/
 infra/terraform.tfstate*
+infra/imports.tf
 infra/*.tfvars
 !infra/*.tfvars.example

.pre-commit-config.yaml

@@ -0,0 +1,38 @@
+# Installed by `just hooks` (prek).
+#   pre-commit  gitleaks on the staged diff
+#   commit-msg  Conventional Commits shape on the first line
+#   pre-push    `just check`, plus `just infra-validate` when infra/ changed
+# `prek run` runs the pre-commit stage on demand; `--hook-stage pre-push` the rest.
+repos:
+  - repo: local
+    hooks:
+      - id: gitleaks
+        name: gitleaks (staged)
+        entry: just _gitleaks-staged
+        language: system
+        pass_filenames: false
+        always_run: true
+        stages: [pre-commit]
+      - id: commit-msg
+        name: conventional commit message
+        entry: >-
+          sh -c 'head -n1 "$1"
+          | grep -Eq "^((build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(\([a-z0-9._/-]+\))?!?:
+          [a-z].{0,81}|(Merge|Revert|fixup!|squash!) .*)$"
+          || { echo "commit message must be type(scope): lower-case summary, at most 82 chars" >&2; exit 1; }' --
+        language: system
+        stages: [commit-msg]
+      - id: check
+        name: just check
+        entry: just check
+        language: system
+        pass_filenames: false
+        always_run: true
+        stages: [pre-push]
+      - id: infra-validate
+        name: just infra-validate
+        entry: just infra-validate
+        language: system
+        pass_filenames: false
+        files: ^infra/
+        stages: [pre-push]

.yamlfmt

@@ -0,0 +1,6 @@
+# Keep line breaks inside folded (>) block scalars: the default re-joins them
+# onto one line, which un-wraps the long PromQL exprs and alert descriptions
+# in config/grafana/alerting/ every time yamlfmt runs.
+formatter:
+  scan_folded_as_literal: true
+  retain_line_breaks_single: true