zackwag/caddy-ui-backend repository overview

⁠caddy/ui — Backend

The API backend for caddy/ui⁠, a web interface for managing your Caddy⁠ server. Built with Node.js and Express.

⁠Features

• Proxies requests to Caddy's admin API (/config, /id, /load)
• Reads and writes the Caddyfile on disk
• Runs caddy validate via Caddy's /adapt admin API endpoint
• Runs caddy fmt and detects Caddy version via docker exec into the running Caddy container (requires Docker socket mount)
• Sorts Caddyfile site blocks on save (public → internal → http)
• Appends, updates, and removes site blocks when routes are managed via the UI
• Fetches routes from all server blocks with recursive upstream extraction for complex route structures
• Health checks use Caddy's reverse proxy upstream pool API as primary source, with TCP fallback for upstreams not yet in the pool
• In-memory rolling uptime tracking per upstream (288-check window, ~2.5 hours)
• Push notifications via ntfy, Discord, Slack, Pushover, or custom webhook — triggered on upstream offline/online and cert expiry
• Configurable notification debounce to suppress repeat alerts
• Reads TLS certificate files from disk and parses expiry dates
• Detects and deletes orphaned, superseded, and expired certificates (resolves issuer directory automatically)
• Root CA cert download via Caddy's /pki/ca/local admin API
• Automatic Caddyfile snapshots on every save with configurable retention
• Tails and streams access logs via SSE
• Parses and updates log configuration in the global Caddyfile block
• Persists server block display names and route notes to disk
• Optional JWT authentication protecting all API endpoints
• Caddy process info and HTTP metrics via Prometheus endpoint
• Metrics enable/disable toggle that modifies the Caddyfile global block
• Optional public /api/metrics/raw endpoint for Prometheus scraping
• Structured JSON logging with configurable log level via LOG_LEVEL
• Enriched status endpoint with route count, upstream health, and uptime for Homepage widget support

⁠Quick Start

services:
  caddy-ui-backend:
    image: zackwag/caddy-ui-backend:latest
    container_name: caddy-ui-backend
    restart: unless-stopped
    ports:
      - 9876:3001
    environment:
      - TZ=America/New_York
      # Optional auth -- leave unset to disable
      - CADDY_UI_USER=admin
      - CADDY_UI_PASSWORD=yourpassword
      - JWT_SECRET=your-long-random-secret
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /docker/caddy/Caddyfile:/etc/caddy/Caddyfile
      - /docker/caddy/logs:/var/log/caddy
      - /docker/caddy-ui:/etc/caddy-ui
      - /docker/caddy/data:/data/caddy
    networks:
      - caddy-ui
    depends_on:
      - caddy

⁠Environment Variables

All variables have sensible defaults. Only set what you need to override.

⁠Authentication

Authentication is disabled by default. Set CADDY_UI_USER, CADDY_UI_PASSWORD, and JWT_SECRET to enable it. All /api/* endpoints are protected and the login screen appears automatically.

Generate a secure JWT secret:

openssl rand -base64 32

⁠Prometheus Metrics

If CADDY_UI_PUBLIC_METRICS=true, the endpoint GET /api/metrics/raw is available without authentication. Example Prometheus scrape config:

scrape_configs:
  - job_name: caddy
    static_configs:
      - targets: ['caddy-ui-backend:3001']
    metrics_path: /api/metrics/raw

Caddy's metrics endpoint must be enabled in your Caddyfile global block:

{
    email [email protected]
    metrics
}

This can be toggled from the caddy/ui Metrics tab without editing the Caddyfile manually.

⁠Homepage Widget

The status endpoint returns enriched data for use with Homepage⁠:

- Caddy:
    href: https://caddy.home
    icon: caddy.png
    widget:
      type: customapi
      url: http://caddy-ui-backend:3001/api/status
      mappings:
        - field: online
          label: Status
          format: text
          remap:
            - value: true
              to: Online
            - value: false
              to: Offline
        - field: routeCount
          label: Routes
          format: number
        - field: upstreamsOnline
          label: Upstreams
          format: number
        - field: uptime
          label: Uptime
          format: text

⁠Required Volumes

⁠API Endpoints

⁠Tags

⁠Source

github.com/zackwag/caddy-ui⁠