115 lines
4.8 KiB
Markdown
115 lines
4.8 KiB
Markdown
# Caddy Proxy Manager
|
||
|
||
Caddy Proxy Manager is a modern control panel for Caddy that simplifies reverse proxy configuration, TLS automation, access control, and observability. The entire application is built with Next.js and ships with a lean dependency set, OAuth2 login, and a battery of tools for managing hosts, redirects, streams, certificates, and Cloudflare DNS-based certificate issuance.
|
||
|
||
## Highlights
|
||
|
||
- **Next.js 14 App Router** UI and API in a single project, backed by an embedded SQLite database.
|
||
- **OAuth2 single sign-on** with PKCE and configurable claim mapping. The first authenticated user becomes the administrator.
|
||
- **End-to-end Caddy orchestration** using the admin API, generating JSON configurations for HTTP, HTTPS, redirects, custom 404 hosts, and TCP/UDP streams.
|
||
- **Cloudflare DNS challenge integration** via xcaddy-built Caddy binary with `cloudflare` and `layer4` modules; credentials are stored in the UI.
|
||
- **Access lists** (HTTP basic auth), custom certificates (managed or imported PEM), and a full audit log of administrative changes.
|
||
- **Default HSTS configuration** (`Strict-Transport-Security: max-age=63072000`) baked into every HTTP route to meet security baseline requirements.
|
||
|
||
## Project Structure
|
||
|
||
```
|
||
.
|
||
├── app/ # Next.js app router (auth, dashboard, APIs)
|
||
├── src/
|
||
│ └── lib/ # Database, Caddy integration, models, settings
|
||
├── docker/ # Dockerfiles for web + Caddy
|
||
├── compose.yaml # Production-ready docker compose definition
|
||
└── data/ # (Generated) SQLite database, TLS material, Caddy data
|
||
```
|
||
|
||
## Requirements
|
||
|
||
- Node.js 20+ (development)
|
||
- Docker + Docker Compose v2 (deployment)
|
||
- OAuth2 identity provider (OIDC compliant preferred)
|
||
- Optional: Cloudflare DNS API token for automated certificate issuance
|
||
|
||
## Quick Start
|
||
|
||
1. **Install dependencies**
|
||
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
> Package downloads require network access.
|
||
|
||
2. **Run the development server**
|
||
|
||
```bash
|
||
npm run dev
|
||
```
|
||
|
||
3. **Configure OAuth2**
|
||
|
||
- Visit `http://localhost:3000/setup/oauth`.
|
||
- Supply your identity provider’s authorization, token, and userinfo endpoints plus client credentials.
|
||
- Sign in; the first user becomes an administrator.
|
||
|
||
4. **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.
|
||
|
||
## Docker Compose
|
||
|
||
`compose.yaml` defines a two-container stack:
|
||
|
||
- `app`: Next.js server with SQLite database and certificate store in `/data`.
|
||
- `caddy`: xcaddy-built binary with Cloudflare DNS provider and layer4 modules. The default configuration responds on `caddyproxymanager.com` and serves the required HSTS header:
|
||
|
||
```caddyfile
|
||
caddyproxymanager.com {
|
||
header Strict-Transport-Security "max-age=63072000"
|
||
respond "Caddy Proxy Manager is running" 200
|
||
}
|
||
```
|
||
|
||
Launch the stack:
|
||
|
||
```bash
|
||
docker compose up -d
|
||
```
|
||
|
||
Environment variables:
|
||
|
||
- `SESSION_SECRET`: random 32+ character string used to sign session cookies.
|
||
- `DATABASE_PATH`: path to the SQLite database (default `/data/app/app.db` in containers).
|
||
- `CERTS_DIRECTORY`: directory for imported PEM files shared with the Caddy container.
|
||
- `CADDY_API_URL`: URL for the Caddy admin API (default `http://caddy:2019` inside the compose network).
|
||
- `PRIMARY_DOMAIN`: default domain served by the bootstrap Caddyfile (defaults to `caddyproxymanager.com`).
|
||
|
||
## Data Locations
|
||
|
||
- `data/app/app.db`: SQLite database storing configuration, sessions, and audit log.
|
||
- `data/certs/`: Imported TLS certificates and keys generated by the UI.
|
||
- `data/caddy/`: Autogenerated Caddy state (ACME storage, etc.).
|
||
|
||
## 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.
|
||
- **Streams:** TCP/UDP forwarding powered by the Caddy layer4 module.
|
||
- **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, OAuth2 endpoints, and Cloudflare DNS credentials.
|
||
|
||
## Development Notes
|
||
|
||
- SQLite schema migrations are embedded in `src/lib/migrations.ts` and run automatically on startup.
|
||
- Caddy configuration is rebuilt on every change and pushed via the admin API. Failures are surfaced to the UI.
|
||
- OAuth2 login uses PKCE and stores session tokens as HMAC-signed cookies backed by the database.
|
||
|
||
## License
|
||
|
||
MIT License © Caddy Proxy Manager contributors.
|