caddy-proxy-manager/README.md

Caddy Proxy Manager

https://caddyproxymanager.com

Caddy Proxy Manager is a modern control panel for Caddy that simplifies reverse proxy configuration, TLS automation, access control, and observability. The stack is built with Next.js 16 (App Router), Material UI, and a lightweight SQLite data layer. It features simple username/password authentication, first-class Caddy admin API integration, and tooling for Cloudflare DNS challenge automation.

Highlights

• Next.js 16 App Router – server components for data loading, client components for interactivity, and a unified API surface.
• Material UI dark mode – fast, responsive dashboard with ready-made components and accessibility baked in.
• Simple authentication – environment-based username/password login configured via docker-compose.
• End-to-end Caddy orchestration – generate JSON for HTTP(S) proxies, redirects, 404 hosts via the Caddy admin API.
• Cloudflare DNS challenge support – xcaddy build bundles the cloudflare DNS and layer4 modules; credentials are configurable in the UI.
• Security-by-default – HSTS (Strict-Transport-Security: max-age=63072000) applied to every managed host.
• Embedded audit log – every configuration change is recorded with actor, summary, and timestamp.

Project Structure

.
├── app/                        # Next.js App Router entrypoint (layouts, routes, server actions)
│   ├── (auth)/                 # Login flow
│   ├── (dashboard)/            # Dashboard layout, feature surface, client renderers
│   ├── api/                    # Route handlers for auth callbacks/logout
│   ├── providers.tsx           # Global MUI theme + CssBaseline
│   └── layout.tsx              # Root HTML/body wrapper
├── src/
│   └── lib/                    # SQLite integration, models, Caddy config builder
├── docker/
│   ├── web/                    # Next.js production image (standalone output)
│   └── caddy/                  # xcaddy build with Cloudflare + layer4 modules
├── docker-compose.yml          # Multi-container deployment (Next.js app + Caddy)
├── data/                       # Generated at runtime (SQLite DB, cert storage, Caddy state)
└── README.md                   # You are here

Dashboard Modules

• ProxyHostsClient.tsx – create/update/delete HTTP(S) reverse proxies, assign certs/access lists.
• RedirectsClient.tsx – manage 301/302 redirects with optional path/query preservation.
• DeadHostsClient.tsx – serve custom offline pages with programmable status codes.
• AccessListsClient.tsx – manage HTTP basic auth credentials and membership.
• CertificatesClient.tsx – import PEMs or request managed ACME certificates.
• SettingsClient.tsx – general metadata and Cloudflare DNS token configuration.
• AuditLogClient.tsx – list chronological administrative activity.

Feature Overview

Authentication & Authorization

• Simple username/password authentication configured via environment variables.
• Credentials set in docker-compose or .env file.
• Session persistence via signed JWT tokens.

Reverse Proxy Management

• HTTP(S) proxy hosts with TLS enforcement, WebSocket + HTTP/2 toggles.
• Redirect hosts with custom status codes and query preservation.
• Dead/maintenance hosts with custom responses.
• Access list (basic auth) integration for protected hosts.
• TLS certificate lifecycle: managed ACME (DNS-01 via Cloudflare) or imported PEMs.

Operations & Observability

• Full audit log with actor/action/summary/time.
• One-click revalidation of Caddy configuration after mutations.
• Migrations run automatically on startup; upgrades are seamless.
• Docker-first deployment, HSTS defaults, Cloudflare DNS automation.

Requirements

• Node.js 20+ (development)
• Docker + Docker Compose v2 (deployment)
• Optional: Cloudflare DNS API token for automated certificate issuance

Quick Start

Development

1. Install dependencies

   npm install
   

2. Create environment file

   cp .env.example .env
   

   Edit .env and set your admin credentials:

   ADMIN_USERNAME=your-username
   ADMIN_PASSWORD=your-secure-password
   SESSION_SECRET=your-random-secret-here
   

3. Run the development server

   npm run dev
   

4. Login

   • Visit http://localhost:3000/login
   • Enter your configured username and password
   • You're now logged in as administrator

5. Configure Cloudflare DNS (optional)

   • Navigate to Settings → Cloudflare DNS.
   • Provide an API token with Zone.DNS:Edit scope and the relevant zone/account IDs.
   • Any managed certificates attached to hosts will now request TLS via DNS validation.

Production Deployment

Docker Compose

docker-compose.yml defines a two-container stack:

• web: Next.js server with SQLite database and certificate store in /data.
• caddy: xcaddy-built binary with Cloudflare DNS provider and layer4 modules.

Launch the stack:

# Create .env file with your credentials
cp .env.example .env

# Edit .env and set secure values for:
# - ADMIN_USERNAME
# - ADMIN_PASSWORD
# - SESSION_SECRET

# Start the containers
docker compose up -d

Environment Variables

Required (Security):

• SESSION_SECRET: Random 32+ character string used to sign session tokens. Generate with: openssl rand -base64 32
• ADMIN_USERNAME: Username for admin login (default: admin)
• ADMIN_PASSWORD: Password for admin login (default: admin)

Optional (Application):

• BASE_URL: Public base URL for the application (default: http://localhost:3000)
• PRIMARY_DOMAIN: Default domain served by Caddy (default: caddyproxymanager.com)
• CADDY_API_URL: URL for the Caddy admin API (default: http://caddy:2019)
• DATABASE_PATH: Path to the SQLite database (default: /app/data/caddy-proxy-manager.db)

⚠️ Important: Always change the default ADMIN_USERNAME and ADMIN_PASSWORD in production!

Data Locations

• data/caddy-proxy-manager.db: SQLite database storing configuration, sessions, and audit log.
• data/certs/: Imported TLS certificates and keys generated by the UI.
• caddy-data/: Autogenerated Caddy state (ACME storage, etc.).
• caddy-config/: Caddy configuration storage.

UI Features

• Proxy Hosts: HTTP(S) reverse proxies with HSTS, access lists, optional custom certificates, and WebSocket support.
• Redirects: 301/302 responses with optional path/query preservation.
• Dead Hosts: Branded responses for offline services.
• Access Lists: Bcrypt-backed basic auth credentials, assignable to proxy hosts.
• Certificates: Managed (ACME) or imported PEM certificates with audit history.
• Audit Log: Chronological record of every configuration change and actor.
• Settings: General metadata and Cloudflare DNS credentials.

Development Notes

• SQLite schema migrations are embedded and run automatically on startup via Prisma.
• Caddy configuration is rebuilt on every change and pushed via the admin API. Failures are surfaced to the UI.
• Authentication uses NextAuth.js with JWT session strategy.
• Type checking: npm run typecheck
• Build: npm run build

Security Considerations

1. Change default credentials: Never use admin/admin in production
2. Use strong SESSION_SECRET: Generate with openssl rand -base64 32
3. Use HTTPS in production: Configure BASE_URL with https:// protocol
4. Restrict network access: Ensure port 3000 is only accessible via reverse proxy
5. Keep updated: Regularly update dependencies and Docker images

License

MIT License © Caddy Proxy Manager contributors.