Skip to content

feat: Self-contained infrastructure with /pan doctor health checks #100

@eltmon

Description

@eltmon

Summary

Make Panopticon fully self-contained by porting all infrastructure from MYN and adding a /pan doctor command to verify setup. This combines the scope of PAN-98 and PAN-99.

Motivation

Currently:

  • MYN has its own myn-traefik container and infra config
  • Panopticon has partial Traefik setup in ~/.panopticon/traefik/
  • No way to verify if a project's infrastructure is correctly configured
  • Users hit cryptic SSL/networking errors with no guidance

Goal: pan install && pan up should "just work" for any project, and pan doctor should diagnose any issues.

Implementation Plan

For each infrastructure component, implement both the setup and the health check:

1. Traefik Container Management

Setup (pan up):

  • Start unified panopticon-traefik container
  • Use config from ~/.panopticon/traefik/
  • Auto-create Docker network if missing

Doctor checks:

  • Traefik container running
  • Ports 80, 443, 8080 available/bound
  • Docker network exists
  • Can reach Traefik dashboard

2. SSL Certificate Management

Setup (pan install + pan workspace create):

  • Run mkcert -install to set up local CA
  • Generate wildcard cert for *.pan.localhost (default)
  • Generate project-specific certs on workspace creation (e.g., *.myn.test)
  • Store in ~/.panopticon/traefik/certs/<domain>/

Doctor checks:

  • mkcert installed
  • Local CA installed in system trust store
  • Default wildcard cert exists
  • Project certs exist (if configured)
  • No certs expired or expiring soon

3. DNS/Hosts Management

Setup (pan workspace create):

  • Add entries to /etc/hosts for workspace domains
  • Track managed entries in ~/.panopticon/hosts.json
  • Prompt for sudo only when needed

Doctor checks:

  • Required hosts entries exist
  • Entries resolve to correct IPs
  • No stale entries for deleted workspaces

4. Per-Project Configuration

Setup (.panopticon.toml in project root):

[networking]
domain = "myn.test"  # Custom domain for this project

[docker]
template = "monorepo"  # Which template to use

Doctor checks:

  • Config file valid TOML
  • Domain has SSL cert
  • Docker template exists

5. Traefik Dynamic Routing

Setup (pan workspace create):

  • Generate dynamic config for workspace services
  • Place in ~/.panopticon/traefik/dynamic/<workspace>.yml
  • Traefik auto-reloads (watches directory)

Doctor checks:

  • Dynamic config files are valid YAML
  • Referenced backends are reachable
  • No orphaned configs for deleted workspaces

6. Docker Environment

Doctor checks:

  • Docker daemon running
  • Docker Compose available
  • Required networks exist
  • No conflicting containers on required ports

7. API Integrations

Doctor checks:

  • LINEAR_API_KEY configured (if using Linear)
  • GitHub CLI authenticated (if using GitHub)
  • API endpoints reachable

/pan doctor Output Format

$ pan doctor

🔍 Panopticon Health Check
══════════════════════════

Docker:
  ✅ Docker daemon running (v24.0.7)
  ✅ Docker Compose available (v2.23.0)
  ✅ Network 'panopticon' exists

Traefik:
  ✅ Container running (panopticon-traefik)
  ✅ Dashboard accessible at http://localhost:8080
  ⚠️  Port 443 bound but cert missing for *.myn.test

SSL Certificates:
  ✅ mkcert installed
  ⚠️  Local CA not in browser trust store
     Run: mkcert -install
  ✅ *.pan.localhost (expires 2028-04-24)
  ❌ *.myn.test - MISSING
     Run: pan doctor --fix

Hosts:
  ✅ pan.localhost → 127.0.0.1
  ✅ feature-min-665.myn.test → 172.29.117.141
  
Integrations:
  ✅ GitHub CLI authenticated (eltmon)
  ✅ Linear API key configured

══════════════════════════
Summary: 2 warnings, 1 error

Run 'pan doctor --fix' to auto-remediate issues.

CLI Commands

Command Description
pan doctor Run all health checks
pan doctor --fix Auto-fix remediable issues
pan doctor --workspace <id> Check specific workspace only
pan doctor --category <cat> Check specific category (docker, ssl, hosts, traefik)

Files to Create/Modify

File Purpose
src/cli/commands/doctor.ts Main doctor command
src/lib/doctor/ Health check modules
src/lib/traefik.ts Traefik management
src/lib/ssl.ts Certificate management
src/lib/hosts.ts /etc/hosts management
src/cli/commands/install.ts Add mkcert setup
src/cli/commands/workspace.ts Add networking setup

Success Criteria

  1. Fresh install: npm install -g panopticon-cli && pan install && pan up works
  2. pan doctor identifies all common configuration issues
  3. pan doctor --fix can remediate most issues automatically
  4. MYN can delete its infra/ directory and use Panopticon instead
  5. No MYN-specific code in Panopticon

Supersedes

  • PAN-98: /pan doctor command
  • PAN-99: Traefik infrastructure port

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions