Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Tasks: caddy-authcrunch-cockpit-tutorial

T000 – Feature spec review

  • Review design.md for completeness and accuracy
  • Confirm Caddy-gated --local-session approach for Cockpit
  • Confirm AuthCrunch Caddyfile syntax against current docs
  • Resolve open design questions (Cockpit auth boundary, custom image, .build support)

T00A – Add Quadlet .build support

This is a new infrastructure prerequisite discovered during spec review. The cockpit-ws container requires a custom Fedora image that installs Cockpit management modules. Quadlet supports .build units; config.toml needs to support them the same way it supports .network and .volume.

  • Add buildDefinition to schemas/config.schema.json ($defs)
  • Add optional build top-level key to schema
  • Implement render_builds() in first-boot-provision.py (follow render_networks()/render_volumes() pattern)
  • Register .build units in quadlet-runtime.json (mode: rootful)
  • Update sync-quadlet to handle .build files
  • Update NixOS test to cover .build rendering and sync
  • Validate that .build Quadlet units trigger image build on first systemctl daemon-reload + container start

T00B – Write cockpit-ws Containerfile

  • Create files/cockpit/Containerfile based on quay.io/fedora/fedora:latest
  • Add Cockpit bridge and management modules via dnf install --setopt=install_weak_deps=False
  • Verify the built image has the required Cockpit modules available
  • Keep the Containerfile minimal (single RUN layer)

T001 – Use Caddy-gated local session auth

  • Remove custom bearer auth script from the example bundle
  • Use Caddy/AuthCrunch as the only public authentication boundary
  • Run Cockpit with --local-session behind Caddy
  • Restrict /cockpit/* to authp/admin

T002 – Write the Caddyfile

  • Configure Entra OIDC identity provider with placeholder values
  • Document how to swap the identity provider block for Google or another OIDC provider
  • Configure authentication portal with JWT signing
  • Configure user transforms for group-to-role mapping
  • Configure authorization policies for admin and user routes
  • Configure reverse proxy to cockpit-ws at localhost:9090
  • Configure /auth* route for authentication portal
  • Configure /cockpit/* route with authorization policy
  • Configure local-only HTTPS with Caddy tls internal
  • Validate Caddyfile syntax against AuthCrunch docs

T003 – Configure Cockpit reverse proxy settings

  • Generate /etc/cockpit/cockpit.conf at container startup
  • Configure Origins from the GATEWAY_DOMAIN environment variable
  • Configure UrlRoot for /cockpit/ path prefix

T004 – Write config.toml

  • Define version = 2
  • Define users.admin.ssh_key with placeholder public key
  • Define network.firewall.inbound.wan with ports 80 and 443 open (TCP)
  • Define activation.required listing caddy-gateway.service and cockpit-ws.service
  • Define caddy-gateway container (rootful, AuthCrunch image)
  • Define cockpit-ws container (rootful, custom build image ref)
  • Define cockpit-ws build section referencing Containerfile
  • Define management network with subnet
  • Define caddy-data volume with local driver
  • Configure Environment keys with placeholder values (AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, JWT_SHARED_KEY)
  • Configure Volume mounts for Caddyfile and host management sockets using ${FILES_DIR} tokens where appropriate
  • Configure Podman socket mount for cockpit-ws container
  • Verify all placeholder values are obvious (<AZURE_TENANT_ID>, etc.)

T005 – Validate config.toml

  • Run first-boot-provision validate on the tutorial config
  • Fix any schema or semantic validation errors
  • Verify all rendered Quadlet files have correct content

T006 – Write NixOS VM test

Skipped. The existing first-boot-provision.nix test already covers all code paths used by the tutorial config (containers, networks, volumes, builds, bundle files, sync-quadlet). A dedicated tutorial test would duplicate coverage without exercising new logic.

T007 – Write tutorial documentation page

  • Write introduction explaining what the tutorial builds
  • Document Azure App Registration prerequisites step by step
  • Document the authentication flow with a diagram
  • Present the complete config.toml with annotations
  • Present the Caddyfile with annotations
  • Present the Containerfile with annotations
  • Document the bundle directory structure
  • Document how to build and apply the bundle
  • Document role mapping (authp/admin for Cockpit, authp/user for app routes)
  • Document local DNS and Caddy internal TLS requirements
  • Document alternate OIDC provider setup for Google and generic providers
  • Document cockpit-podman container/socket integration and native-host alternative
  • Document security considerations and production hardening notes
  • Add placeholders table listing all values that must be substituted

T008 – Update docs/src/SUMMARY.md

  • Create a Tutorials section in SUMMARY.md (does not exist yet)
  • Add tutorial entry under the new Tutorials section

T009 – Update planned-features.md

  • Update caddy-authcrunch-cockpit-tutorial status to in-progress

T999 – Feature close-out

  • All tasks T00A-T009 completed
  • Tutorial config passes first-boot-provision validate
  • NixOS VM test passes (T006 skipped; existing test covers code paths)
  • Documentation builds without errors
  • design.md and delivered behavior agree
  • No unresolved design questions remain

Items deferred to hardware validation

  • T00A: Validate .build Quadlet units trigger image build on daemon-reload
  • T00B: Verify built image has the required Cockpit modules available