Skip to content

CLAUDE.md

Latest commit

 

History

History
77 lines (60 loc) · 3.29 KB

CLAUDE.md

File metadata and controls

77 lines (60 loc) · 3.29 KB

pangolin-companion

Auto-provisions Pangolin reverse-proxy resources from Docker container labels.

Architecture

Flat package main. Files:

main.go        — config loading, wire-up, signal handling, graceful shutdown
config.go      — Config struct, envOrDefault helper, validation (fail-fast at startup)
watcher.go     — Docker event streaming (start / die), dispatches to reconciler
labels.go      — Parse/validate pangolin.* labels into ResourceSpec
reconciler.go  — Startup reconciliation, create/delete orchestration, Compose dedup
pangolin.go    — Pangolin Integration API client (create resource, create target, delete)
store.go       — JSON-backed containerID → resourceID persistent map
health.go      — /healthz, /status HTTP endpoints

Build & Run

go build -o pangolin-companion .

PANGOLIN_API_KEY=id.secret PANGOLIN_ORG_ID=org1 \
  PANGOLIN_SITE_ID=site1 PANGOLIN_DOMAIN_ID=dom1 \
  ./pangolin-companion

Test

go test -v ./...
# race detector requires CGO (gcc): CGO_ENABLED=1 go test -race -v ./...

Docker

docker compose up -d

Environment Variables

Variable Default Required Description
PANGOLIN_API_KEY — yes API key (keyId.keySecret)
PANGOLIN_ORG_ID — yes Pangolin organization ID
PANGOLIN_SITE_ID — yes Default site ID for new resources
PANGOLIN_DOMAIN_ID — yes Default domain ID for new resources
PANGOLIN_API_URL http://10.1.100.2:3003 no Integration API base URL
CLEANUP_ON_STOP true no Delete resource when container stops
STATE_FILE /data/state.json no Path to persistent state JSON
HEALTH_PORT 8080 no HTTP health endpoint port

Label Schema

labels:
  pangolin.enable: "true"           # required — opt-in flag
  pangolin.name: "My App"           # required — display name in Pangolin UI
  pangolin.subdomain: "app"         # required — → app.<base-domain>
  pangolin.target.port: "8080"      # required — container port to proxy to
  pangolin.site-id: "abc123"        # optional — override PANGOLIN_SITE_ID
  pangolin.domain-id: "xyz456"      # optional — override PANGOLIN_DOMAIN_ID
  pangolin.ssl: "false"             # optional — TLS to backend (default false)
  pangolin.sso: "false"             # optional — Pangolin SSO gate (default false)

Key Patterns

  • Config: envOrDefault() helper, validate required fields at startup (fail fast)
  • Docker SDK: github.com/docker/docker/client for event streaming + ContainerInspect
  • State: JSON file at STATE_FILE, loaded on startup, written after every mutation
  • Pangolin API: x-api-key header auth, PUT to create, DELETE to remove
  • Compose dedup: com.docker.compose.project/service key prevents duplicate resources
  • Graceful shutdown: context.WithCancel propagated to watcher + health server