Skip to main content

Project: Harness Engineering (Docs/Auth/Dashboard)

Purpose​

Turn the current docs/auth/dashboard setup into a reliable, repeatable system by applying harness engineering principles:

  • humans steer, agents execute
  • repo/KB is the system of record
  • verification + feedback loops are mandatory
  • automation scripts reduce manual work

Scope​

In scope​

  • Nginx Proxy Manager (edge)
  • Authentik (SSO)
  • Docusaurus KB deployment
  • Homepage dashboard (control room)
  • Standard folder/layout conventions on the VM
  • SOP + stack-map documentation
  • Healthcheck and update scripts

Out of scope​

  • Care Flow orchestration (separate project)
  • GitLab (separate SOP/project)

Owner / Team​

  • Owner: Arif
  • Team: (assign)

Status​

  • Status: In progress
  • Start date: 2026-02-13
  • Target date: (set)

Architecture​

High-level flow​

Internet → NPM (TLS + routing + forward-auth) → services

  • auth.* → Authentik
  • docs.* → Docusaurus
  • kb.* → redirect to docs

System of record​

  • Docusaurus KB pages store:
    • SOPs
    • stack map
    • troubleshooting

Prereqs​

  • DNS records exist for docs/kb/auth
  • Router forwarding 80/443 → edge VM
  • VM has Docker + docker compose

Inputs​

Deliverables​

  • Stack Map KB page (single source of truth): IPs, ports, folders, domains → targets
  • SOPs are updated to match reality (NPM + Authentik + Private Docs)
  • Standard VM layout:
    • ~/stack/npm/
    • ~/stack/authentik/
    • ~/apps/docusaurus-kb/
    • ~/stack/homepage/
  • check-stack.sh (health checks)
  • update-stack.sh (safe update procedure)
  • Homepage tiles: docs/auth + internal tools (LAN)

Procedure (Step-by-step)​

Step 1 — Create Stack Map page​

Create /ops/stack-map in KB with:

  • VM IP
  • local ports
  • public domains
  • folder locations
  • common failure modes (127.0.0.1 binding, redirect loops)

Step 2 — Add mechanical verification​

Create a single command to verify:

  • docker containers running
  • local HTTP endpoints respond
  • public domains respond

Step 3 — Add update workflow​

Create a single command to:

  • pull latest repo changes
  • update containers
  • rebuild/serve docs

Step 4 — Dashboard as feedback loop​

Homepage should link:

  • docs
  • auth
  • NPM admin (LAN-only)
  • GitHub repos
  • (optional) last healthcheck result

Config​

  • Define canonical domains + redirect rules
  • Ensure Authentik forward-auth is the only gate for docs

Verification​

  • Incognito → docs redirects to Authentik login
  • After login → docs loads
  • check-stack.sh passes

Rollback​

  • Remove forward-auth snippet from NPM (restore public docs)
  • Rollback containers to previous images (if used)

Troubleshooting​

  • 502 errors: check NPM upstream reachability + port bindings
  • Redirect loops: check provider external host + outpost config
  • Authentik media permissions: ensure /media volume is writable

References​

Changelog​

  • 2026-02-13: Created project plan page.