Caddy Proxy Manager

Web interface for managing Caddy Server reverse proxies and certificates.

Report Bug • Request Feature

Overview

This project provides a web UI for Caddy Server, eliminating the need to manually edit JSON configurations or Caddyfiles. It handles reverse proxies, access lists, and certificate management through a shadcn/ui interface. Built with Next.js 16, React 19, shadcn/ui, Tailwind CSS, Drizzle ORM, and TypeScript.

---

Installation

git clone https://github.com/fuomag9/caddy-proxy-manager.git
cd caddy-proxy-manager
cp .env.example .env
# Edit .env with your credentials
docker compose up -d

Access at http://localhost:3000/login

Data persists in Docker volumes (caddy-manager-data, caddy-data, caddy-config, caddy-logs).

---

Features

• Proxy Hosts - Reverse proxies with custom headers, multiple upstreams, load balancing, and enable/disable toggle
• L4 Proxy Hosts - TCP/UDP stream proxying with TLS SNI matching, proxy protocol (v1/v2), load balancing, health checks, and per-host geo blocking
• WAF - Web Application Firewall powered by Coraza with optional OWASP Core Rule Set (SQLi, XSS, LFI, RCE). Per-host enable/disable, global and per-host rule suppression, custom SecLang directives, and a searchable event log with severity and blocked/detected classification
• Analytics - Live traffic charts, protocol breakdown, country map, top user agents, and blocked request log with configurable time ranges
• Search & Pagination - Server-side search and pagination on all data tables (proxy hosts, access lists, audit log, certificates)
• Geo Blocking - Block or allow traffic by country, continent, ASN, CIDR range, or exact IP per proxy host
• Access Lists - Multi-account HTTP basic auth protection assignable per proxy host
• Certificates - Automatic HTTPS for every proxy host via Caddy ACME (Let's Encrypt / ZeroSSL), with issuer and expiry visibility + manual SSL/TLS import. Built-in CA for issuing internal client certificates
• Instance Sync - Master/slave configuration sync for multi-instance deployments. The master pushes proxy hosts, certificates, access lists, and settings to slaves on every change
• Settings - ACME email, Cloudflare DNS-01, upstream DNS pinning defaults, Authentik outpost, Prometheus metrics
• Audit Log - Searchable configuration change history with user attribution
• Mobile UI - Fully responsive interface optimised for iPhone and other narrow viewports

---

Configuration

Environment Variables

Variable	Description	Default	Required
SESSION_SECRET	Session encryption key (32+ chars)	None	Yes
ADMIN_USERNAME	Admin login username	admin	Yes
ADMIN_PASSWORD	Admin password (see requirements below)	admin (dev only)	Yes
BASE_URL	Public URL where users access the dashboard. Required for OAuth - must match redirect URI	http://localhost:3000	Yes (if using OAuth)
CADDY_API_URL	Caddy Admin API endpoint	http://caddy:2019 (prod) http://localhost:2019 (dev)	No
DATABASE_URL	SQLite database URL	file:/app/data/caddy-proxy-manager.db	No
CERTS_DIRECTORY	Certificate storage directory	./data/certs	No
CADDY_CERTS_DIR	Caddy cert storage path used for ACME metadata scanning (non-default deployments)	/caddy-data/caddy/certificates	No
LOGIN_MAX_ATTEMPTS	Max login attempts before rate limit	5	No
LOGIN_WINDOW_MS	Rate limit window in milliseconds	300000 (5 min)	No
LOGIN_BLOCK_MS	Rate limit block duration in milliseconds	900000 (15 min)	No
OAUTH_ENABLED	Enable OAuth2/OIDC authentication	false	No
OAUTH_PROVIDER_NAME	Display name for OAuth provider	OAuth2	No
OAUTH_CLIENT_ID	OAuth2 client ID	None	No
OAUTH_CLIENT_SECRET	OAuth2 client secret	None	No
OAUTH_ISSUER	OAuth2 OIDC issuer URL	None	No
OAUTH_AUTHORIZATION_URL	Optional OAuth authorization endpoint override	Auto-discovered from OAUTH_ISSUER	No
OAUTH_TOKEN_URL	Optional OAuth token endpoint override	Auto-discovered from OAUTH_ISSUER	No
OAUTH_USERINFO_URL	Optional OAuth userinfo endpoint override	Auto-discovered from OAUTH_ISSUER	No
OAUTH_ALLOW_AUTO_LINKING	Allow auto-linking OAuth identities to existing users	false	No
INSTANCE_MODE	Instance role: standalone, master, or slave	standalone	No
INSTANCE_SYNC_TOKEN	Bearer token slaves use to authenticate sync requests	None	No (required if slave)
INSTANCE_SLAVES	JSON array of slave instances for the master to push to	None	No
INSTANCE_SYNC_INTERVAL	Periodic sync interval in seconds (0 = disabled)	0	No
INSTANCE_SYNC_ALLOW_HTTP	Allow sync over HTTP (for internal Docker networks)	false	No

Production Requirements:

• SESSION_SECRET: 32+ characters (openssl rand -base64 32)
• ADMIN_PASSWORD: 12+ chars with uppercase, lowercase, numbers, and special characters

Development mode (NODE_ENV=development) allows default admin/admin credentials.

---

Security

• Production enforces strong passwords (12+ chars, mixed case, numbers, special characters)
• 32+ character session secrets required
• Login rate limiting: 5 attempts per 5 minutes
• Audit trail for all configuration changes
• Supports OAuth2/OIDC for SSO

Production Setup:

export SESSION_SECRET=$(openssl rand -base64 32)
export ADMIN_USERNAME="admin"
export ADMIN_PASSWORD="YourStr0ng-P@ssw0rd123!"
docker compose up -d

Limitations:

• Certificate private keys stored unencrypted in SQLite
• In-memory rate limiting (not suitable for multi-instance deployments)

---

Certificate Management

Caddy automatically obtains Let's Encrypt certificates for all proxy hosts.

Cloudflare DNS-01 (optional): Configure in Settings with a Cloudflare API token (Zone.DNS:Edit permissions).

Custom Certificates (optional): Import your own certificates via the Certificates page. Private keys are stored unencrypted in SQLite.

---

Geo Blocking

Geo blocking is configured per proxy host. It requires MaxMind GeoLite2 databases (see GeoIP Setup).

Rule types

Type	Example	Description
Country	DE	ISO 3166-1 alpha-2 country code
Continent	EU	AF, AN, AS, EU, NA, OC, SA
ASN	24940	Autonomous System Number
CIDR	91.98.150.0/24	IP range in CIDR notation
IP	91.98.150.103	Exact IP address

Rules can be block or allow. Allow rules take precedence over block rules — you can block an entire continent and then allow specific IPs or ASNs through.

GeoIP Setup

Geo blocking requires MaxMind GeoLite2 Country and/or ASN databases. Use the bundled geoipupdate service:

1. Register for a free MaxMind account at maxmind.com
2. Generate a license key with GeoLite2-Country and GeoLite2-ASN permissions
3. Add to your .env:

   GEOIPUPDATE_ACCOUNT_ID=your-account-id
   GEOIPUPDATE_LICENSE_KEY=your-license-key
   

4. Start with the geoipupdate profile:

   docker compose --profile geoipupdate up -d

The databases are stored in the geoip-data Docker volume and shared between the web and Caddy containers.

---

WAF (Web Application Firewall)

The WAF is powered by Coraza and integrates the OWASP Core Rule Set.

Enable globally in WAF → Settings, then optionally override per proxy host. Two modes:

• Block — requests matching rules are rejected with 403
• Detect — requests are logged but not blocked

OWASP CRS covers SQLi, XSS, LFI, RCE, and more (enabled by default when WAF is on).

Rule suppression — suppress noisy rules globally or per host from the event detail drawer or the Suppressed Rules tab.

Custom directives — any ModSecurity SecLang syntax is accepted, e.g.:

SecRule REQUEST_URI "@beginsWith /api/" "id:9001,phase:1,ctl:ruleEngine=Off,nolog"

---

Instance Sync

Run a master instance that pushes configuration to one or more slaves on every change.

# Master
INSTANCE_MODE=master
INSTANCE_SLAVES='[{"name":"replica","url":"https://replica.example.com","token":"<32-char-token>"}]'

# Slave
INSTANCE_MODE=slave
INSTANCE_SYNC_TOKEN=<32-char-token>

Synced data: proxy hosts, certificates, access lists, and settings. User accounts are not synced.

Use HTTPS slave URLs in production. Set INSTANCE_SYNC_ALLOW_HTTP=true only for internal Docker networks.

See the Environment Variables Reference for all INSTANCE_* options.

---

Upstream DNS Pinning

You can enable upstream DNS pinning globally (Settings → Upstream DNS Pinning) and override per host (Proxy Host → Upstream DNS Pinning).

When enabled, hostname upstreams are resolved during config save/reload and written to Caddy as concrete IP dials. Address family selection supports:

• both (preferred, resolves AAAA then A with IPv6 preference)
• ipv6
• ipv4

Important HTTPS Limitation

If one reverse proxy handler contains multiple different HTTPS upstream hostnames, HTTPS pinning is skipped for those HTTPS upstreams to avoid TLS SNI mismatch. In that case, hostname dials are kept for those HTTPS upstreams.

HTTP upstreams in the same handler are still eligible for pinning.

---

OAuth Authentication

Supports any OIDC-compliant provider (Authentik, Keycloak, Auth0, etc.).

# Set your public URL (REQUIRED for OAuth to work)
BASE_URL=https://caddy-manager.example.com

OAUTH_ENABLED=true
OAUTH_PROVIDER_NAME="Authentik"  # Display name
OAUTH_CLIENT_ID=your-client-id
OAUTH_CLIENT_SECRET=your-client-secret
OAUTH_ISSUER=https://auth.example.com/application/o/app/

Redirect URI Configuration:

You must configure this redirect URI in your OAuth provider:

{BASE_URL}/api/auth/callback/oauth2

Examples:

• http://localhost:3000/api/auth/callback/oauth2 (development)
• https://caddy-manager.example.com/api/auth/callback/oauth2 (production)

The BASE_URL environment variable must match exactly where users access your dashboard.

OAuth login appears on the login page alongside credentials. Users can link OAuth to existing accounts from the Profile page.

---

Roadmap

• Multi-user RBAC
• Additional DNS providers (Route53, Namecheap, etc.)

Open an issue for feature requests.

---

Contributing

Contributions welcome:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/name)
3. Commit changes (git commit -m 'Add feature')
4. Push to branch (git push origin feature/name)
5. Open a Pull Request

• Follow the existing code style (TypeScript, Prettier formatting)
• Add tests for new features when applicable
• Update documentation for user-facing changes
• Keep commits focused and write clear commit messages

---

Support

• Issues: GitHub Issues for bugs and feature requests
• Discussions: GitHub Discussions for questions and ideas

---

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Acknowledgments

• Caddy Server – The amazing web server that powers this project
• Nginx Proxy Manager – The original project
• Next.js – React framework for production
• shadcn/ui – Beautifully designed components built on Radix UI and Tailwind CSS
• Drizzle ORM – Lightweight SQL migrations and type-safe queries

---

⬆ back to top