akanealw/caddy-proxy-manager
1
0
Fork 0
Code Issues Pull Requests Actions 3 Packages Projects Releases Wiki Activity

better readme

Browse Source
This commit is contained in:
fuomag9
2025-12-10 18:28:03 +01:00
parent 5d0593e56c
commit 2fd11c8fd2
2 changed files with 124 additions and 209 deletions
Download Patch File Download Diff File Expand all files Collapse all files

331
README.md
View File

@@ -1,134 +1,85 @@
<div align="center">
# Caddy Proxy Manager
### Modern Web UI for Caddy Server
Web interface for managing [Caddy Server](https://caddyserver.com/) reverse proxies, redirects, and certificates.
[![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)](https://github.com/fuomag9/caddy-proxy-manager)
[![License](https://img.shields.io/badge/license-MIT-green.svg)]([LICENSE](https://mit-license.org))
[![License](https://img.shields.io/badge/license-MIT-green.svg)](https://mit-license.org)
[![Next.js](https://img.shields.io/badge/Next.js-16-black)](https://nextjs.org/)
[![Docker](https://img.shields.io/badge/docker-ready-blue)](https://www.docker.com/)
[Website](https://caddyproxymanager.com) • [Documentation](#getting-started) • [Report Bug](https://github.com/fuomag9/caddy-proxy-manager/issues) • [Request Feature](https://github.com/fuomag9/caddy-proxy-manager/issues)
[Report Bug](https://github.com/fuomag9/caddy-proxy-manager/issues) • [Request Feature](https://github.com/fuomag9/caddy-proxy-manager/issues)
</div>
<img width="1525" height="873" alt="Dashboard screenshot" src="https://github.com/user-attachments/assets/297cc5b9-5185-4ce3-83ef-b5d87d16fcb4" />
## Overview
This project provides a web UI for Caddy Server, eliminating the need to manually edit JSON configurations or Caddyfiles. It handles reverse proxies, redirects, dead hosts (maintenance pages), access lists, and certificate management through a Material UI interface.
**Key features:**
- Reverse proxy configuration with upstream pools and custom headers
- HTTP basic auth access lists
- Automatic HTTPS via Caddy's ACME (Let's Encrypt) with Cloudflare DNS-01 support
- Custom certificate import (internal CA, wildcards, etc.)
- Audit logging of all configuration changes
- Login rate limiting and session management
- Built with Next.js 16, React 19, Drizzle ORM, and TypeScript
---
## Welcome! 👋
## Installation
Caddy Proxy Manager brings a beautiful, intuitive web interface to [Caddy Server](https://caddyserver.com/), the modern web server with automatic HTTPS. Whether you're managing reverse proxies, configuring redirects, or handling SSL/TLS certificates, we've designed this tool to make your life easier.
**No complex multi-tenancy. No unnecessary bloat. Just a clean, secure, and powerful admin interface for your Caddy infrastructure.**
<img width="1525" height="873" alt="image" src="https://github.com/user-attachments/assets/297cc5b9-5185-4ce3-83ef-b5d87d16fcb4" />
---
## Why Caddy Proxy Manager?
### Built for Simplicity
- **Point-and-click configuration** – No need to manually edit JSON config files or learn Caddyfile syntax
- **Works out of the box** – Deploy with Docker Compose in under 2 minutes
- **Automatic HTTPS** – Leverage Caddy's built-in ACME support with Cloudflare DNS-01 challenges
- **Visual dashboard** – Beautiful Material UI dark theme that's easy on the eyes
### Built for Control
- **Complete audit trail** – Every configuration change is logged with timestamp, actor, and details
- **Access management** – Create and assign HTTP basic-auth access lists to protect your services
- **Certificate lifecycle** – Manage ACME certificates or import your own PEM files
- **Upstream health** – Configure reverse proxy pools with custom headers and health checks
### Built for Security
- **Hardened by default** – Login throttling, strict session management, HSTS injection
- **Admin-first design** – Single admin account with production credential enforcement
- **Secure secrets** – API tokens never displayed after initial entry, restrictive file permissions
- **Modern stack** – Built on Next.js 16, React 19, and Drizzle ORM with TypeScript throughout
---
## Quick Start
### Docker Compose (Recommended)
Get up and running in 2 minutes with our Docker setup:
### Docker Compose
```bash
# 1. Clone the repository
git clone https://github.com/yourusername/caddy-proxy-manager.git
git clone https://github.com/fuomag9/caddy-proxy-manager.git
cd caddy-proxy-manager
# 2. Configure your environment
cp .env.example .env
# 3. Edit .env with secure credentials
# ADMIN_USERNAME=your-admin
# ADMIN_PASSWORD=your-strong-password-min-12-chars
# SESSION_SECRET=$(openssl rand -base64 32)
# 4. Launch the stack
# Edit .env with your credentials (see Configuration section below)
docker compose up -d
```
**What you get:**
- `web` – Next.js application server with SQLite database
- `caddy` – Custom Caddy build with Cloudflare DNS and Layer4 modules
The stack includes:
- `web` - Next.js app with SQLite database
- `caddy` - Custom Caddy build (includes Cloudflare DNS and Layer4 modules)
**Data persistence:**
- `./data` → Application database and imported certificates
- `./caddy-data` → ACME certificates and storage
- `./caddy-config` → Caddy runtime configuration
Data is persisted in:
- `./data` - Application database and certificates
- `./caddy-data` - ACME certificates
- `./caddy-config` - Caddy runtime config
### Local Development
Prefer to run locally? No problem:
```bash
# 1. Install dependencies
npm install
# 2. Configure environment
cp .env.example .env
# 3. Set your credentials in .env
# ADMIN_USERNAME=admin
# ADMIN_PASSWORD=your-password
# SESSION_SECRET=$(openssl rand -base64 32)
# 4. Start the development server
# Edit .env with your credentials
npm run dev
```
Visit `http://localhost:3000/login` and sign in with your credentials.
Access the interface at `http://localhost:3000/login`.
**Note:** Login attempts are rate-limited to 5 tries per 5 minutes. After repeated failures, wait 15 minutes before trying again.
Login attempts are rate-limited (5 attempts per 5 minutes, 15 minute lockout after repeated failures).
---
## Features
### Core Modules
| Module | Description |
|--------|-------------|
| **Proxy Hosts** | Configure HTTP/HTTPS reverse proxies with upstream pools, custom headers, and Authentik forward auth |
| **Redirects** | Set up 301/302 redirects with optional query string preservation |
| **Dead Hosts** | Display branded maintenance pages with custom status codes |
| **Access Lists** | Create HTTP basic-auth user lists and assign them to proxy hosts |
| **Certificates** | Import custom SSL/TLS certificates (internal CA, wildcards, etc.) - Caddy auto-manages public certs |
| **Settings** | Configure primary domain, ACME email, and Cloudflare DNS automation |
| **Audit Log** | Review chronological feed of all administrative actions |
| **Proxy Hosts** | HTTP/HTTPS reverse proxies with upstream pools, custom headers, Authentik forward auth |
| **Redirects** | 301/302 redirects with optional query string preservation |
| **Dead Hosts** | Maintenance pages with custom status codes |
| **Access Lists** | HTTP basic auth user management for proxy hosts |
| **Certificates** | Custom SSL/TLS certificate import (Caddy auto-manages Let's Encrypt) |
| **Settings** | ACME email and Cloudflare API configuration |
| **Audit Log** | Chronological log of all configuration changes |
### Technical Highlights
- **Next.js 16 App Router** – Server components, streaming, and server actions
- **Material UI Components** – Responsive design with dark theme
- **Direct Caddy Integration** – Generates JSON config and pushes via Caddy Admin API
- **Drizzle ORM** – Type-safe SQLite access with checked-in SQL migrations
- **SQLite Database** – Zero-configuration persistence with full ACID compliance
- **Cloudflare DNS-01** – Automated wildcard certificate issuance
- **bcrypt Authentication** – Industry-standard password hashing for access lists
**Technical Stack:**
- Next.js 16 App Router with React 19
- Material UI (dark theme)
- Drizzle ORM with SQLite
- Direct integration with Caddy Admin API
- Cloudflare DNS-01 challenge support for wildcard certificates
- bcrypt for access list password hashing
---
@@ -143,7 +94,7 @@ Visit `http://localhost:3000/login` and sign in with your credentials.
| `ADMIN_PASSWORD` | Admin password (see requirements below) | `admin` (dev only) | **Yes** |
| `BASE_URL` | Public URL of the dashboard | `http://localhost:3000` | No |
| `CADDY_API_URL` | Caddy Admin API endpoint | `http://caddy:2019` (prod)<br/>`http://localhost:2019` (dev) | No |
| `DATABASE_URL` | SQLite database URL | `file:./data/caddy-proxy-manager.db` | No |
| `DATABASE_URL` | SQLite database URL | `file:/app/data/caddy-proxy-manager.db` | No |
| `CERTS_DIRECTORY` | Certificate storage directory | `./data/certs` | No |
| `LOGIN_MAX_ATTEMPTS` | Max login attempts before rate limit | `5` | No |
| `LOGIN_WINDOW_MS` | Rate limit window in milliseconds | `300000` (5 min) | No |
@@ -179,176 +130,145 @@ The application will **fail to start** in production if these requirements are n
```
caddy-proxy-manager/
├── app/ # Next.js App Router
│ ├── (auth)/ # Authentication pages
│ ├── (dashboard)/ # Dashboard layout and feature modules
│ ├── api/ # API routes (NextAuth, health checks)
│ ├── globals.css # Global styles
│ └── providers.tsx # Theme and context providers
├── src/lib/ # Core business logic
│ ├── models/ # Database models and operations
│ ├── caddy/ # Caddy config generation
│ └── auth/ # Authentication helpers
├── drizzle/ # Database migrations
├── app/ # Next.js App Router
│ ├── (auth)/ # Authentication pages
│ ├── (dashboard)/ # Dashboard and feature modules
│ ├── api/ # API routes
│ └── providers.tsx # Theme providers
├── src/lib/ # Core business logic
│ ├── models/ # Database models
│ ├── caddy/ # Caddy config generation
│ └── auth/ # Authentication
├── drizzle/ # Database migrations
├── docker/
│ ├── web/ # Next.js production Dockerfile
│ └── caddy/ # Custom Caddy build (xcaddy + modules)
├── docker-compose.yml # Production deployment stack
└── data/ # Runtime data (SQLite + certificates)
│ ├── web/ # Next.js Dockerfile
│ └── caddy/ # Custom Caddy build
├── docker-compose.yml # Deployment stack
└── data/ # SQLite + certificates
```
---
## Security Features
## Security
We take security seriously. Here's what's built-in:
**Authentication:**
- Production mode enforces strong credentials (12+ chars, mixed case, numbers, special characters)
- Application refuses to start with weak passwords in production
- 32+ character session secrets required
- Login rate limiting: 5 attempts per 5 minutes, 15 minute lockout
- Single admin user model
### Authentication & Authorization
- **Strict Credential Enforcement** – Application refuses to start in production with weak/default credentials
- **Password Complexity** – Enforced minimum 12 chars with uppercase, lowercase, numbers, and special characters
- **Session Secret Validation** – 32+ character secrets required with automatic detection of insecure placeholders
- **Login Throttling** – IP + username based rate limiting (5 attempts / 5 minutes)
- **Admin-Only Mutations** – All configuration changes require admin privileges
- **Fail-Fast Validation** – Security checks run at server startup, not at first request
**Data Protection:**
- Imported certificates stored with `0600` permissions
- Session encryption with validated secrets
- API tokens redacted after initial entry
- Audit trail for all configuration changes
- HSTS headers applied to managed hosts
### Data Protection
- **Certificate Protection** – Imported certificates stored with `0600` permissions
- **Session Encryption** – All sessions encrypted with validated secrets
- **Secret Redaction** – API tokens never rendered back to the browser
- **Audit Trail** – Immutable log of all administrative actions
### Infrastructure Security
- **HSTS Headers** – Strict-Transport-Security automatically applied to managed hosts
- **Secure Defaults** – All security features enabled by default
- **Docker Security** – Minimal attack surface with multi-stage builds
- **Privilege Dropping** – Containers run as non-root users
### Security Best Practices
**For Production Deployments:**
**Production Setup:**
```bash
# 1. Generate a secure session secret
export SESSION_SECRET=$(openssl rand -base64 32)
# 2. Create strong admin credentials
export ADMIN_USERNAME="admin" # Any username is fine
export ADMIN_PASSWORD="Your-Str0ng-P@ssw0rd!" # 12+ chars, mixed case, numbers, special chars
# 3. Store credentials securely
export ADMIN_USERNAME="admin"
export ADMIN_PASSWORD="YourStr0ng-P@ssw0rd123!"
echo "SESSION_SECRET=$SESSION_SECRET" > .env
echo "ADMIN_USERNAME=$ADMIN_USERNAME" >> .env
echo "ADMIN_PASSWORD=$ADMIN_PASSWORD" >> .env
chmod 600 .env # Restrict file permissions
chmod 600 .env
```
**For Development:**
**Development Mode:**
```bash
# Development mode allows default credentials
export NODE_ENV=development
npm run dev
# Login with admin/admin
```
**Known Limitations:**
- Imported certificate keys stored in SQLite without encryption (planned enhancement)
- In-memory rate limiting (requires Redis/Memcached for multi-instance deployments)
- No 2FA support yet (planned enhancement)
**Limitations:**
- Certificate private keys stored unencrypted in SQLite
- In-memory rate limiting (not suitable for multi-instance deployments)
- No 2FA support
---
## Certificate Management
### Automatic HTTPS (Default)
**Automatic HTTPS (Default):**
Caddy automatically handles SSL/TLS certificates for all proxy hosts:
Caddy automatically obtains and renews Let's Encrypt certificates for all proxy hosts. Just add a domain and certificates are handled automatically.
- **Zero Configuration**: Just add a domain to a proxy host - certificates are obtained automatically
- **Auto-Renewal**: Certificates renew automatically before expiration
- **Multiple Domains**: Each proxy host can have multiple domains with automatic cert management
- **Wildcard Support**: Use Cloudflare DNS-01 challenge for wildcard certificates
For wildcard certificates, configure Cloudflare DNS-01 in Settings (see below).
**No action required** - this works out of the box!
**Custom Certificates (Optional):**
### Custom Certificates (Optional)
Import your own certificates for:
- Internal CA certificates
- Certificates from other providers
- Compliance requirements
Import your own certificates when you need to:
- **Internal CA**: Use certificates from your organization's Certificate Authority
- **Pre-existing Certs**: Reuse certificates you already have
- **Special Requirements**: Compliance, security policies, or specific certificate features
- **Wildcard from DNS Provider**: Import wildcard certificates from your DNS provider
**How to import:**
1. Navigate to **Certificates** page
2. Click **Import Custom Certificate**
3. Provide certificate name and domains
To import:
1. Go to Certificates page
2. Click Import Custom Certificate
3. Enter certificate name and domains
4. Paste certificate PEM (full chain recommended)
5. Paste private key PEM
6. Save and assign to proxy hosts as needed
6. Assign to proxy hosts as needed
**Security Note**: Imported private keys are stored in the database. Ensure your `.env` file and database have restricted permissions (`chmod 600`).
Note: Private keys are stored in SQLite without encryption.
---
## Cloudflare DNS Automation
## Cloudflare DNS-01 Setup
To enable automatic SSL certificates with Cloudflare DNS-01 challenges:
For wildcard certificates or DNS-01 challenge:
1. Navigate to **Settings** in the dashboard
2. Generate a Cloudflare API token with `Zone.DNS:Edit` permissions
3. Enter your token (it's never pre-filled or displayed again for security)
4. Optionally provide Zone ID / Account ID for multi-zone setups
5. Configure ACME email address for certificate notifications
1. Go to Settings
2. Create a Cloudflare API token with `Zone.DNS:Edit` permissions
3. Enter token (not displayed again after saving)
4. Optionally add Zone ID / Account ID
5. Set ACME email for certificate notifications
**To revoke a token:** Select "Remove existing token" in Settings and submit.
To revoke: Select "Remove existing token" in Settings.
---
## Development
### Available Scripts
| Command | Description |
|---------|-------------|
| `npm run dev` | Start development server with hot reload |
| `npm run build` | Create optimized production build |
| `npm run dev` | Development server with hot reload |
| `npm run build` | Production build |
| `npm start` | Run production server |
| `npm run typecheck` | Run TypeScript type checking |
| `npm run typecheck` | TypeScript type checking |
| `npm run db:migrate` | Apply database migrations |
### Development Notes
- **Database:** Drizzle migrations live in `/drizzle`. Run `npm run db:migrate` to apply them to your local SQLite file.
- **Caddy Config:** Rebuilt on each mutation and pushed to Caddy Admin API. Errors are surfaced in the UI.
- **Rate Limiting:** Kept in-memory per Node process. For horizontal scaling, use Redis/Memcached.
- **Authentication:** Currently supports single admin user. Multi-role support requires architecture changes.
**Notes:**
- Drizzle migrations are in `/drizzle`
- Caddy config regenerated on each mutation and pushed via Admin API
- Rate limiting is in-memory (not suitable for multi-instance deployments)
- Single admin user architecture
---
## Roadmap
We're actively working on these improvements:
- [ ] Multi-user support with role-based access control
- [ ] Additional DNS providers (Namecheap, Route53, etc.)
- [ ] Metrics and monitoring dashboard
- [ ] Backup and restore functionality
- [ ] Multi-user RBAC
- [ ] Additional DNS providers (Route53, Namecheap, etc.)
- [ ] Backup/restore
- [ ] API for programmatic configuration
Have ideas? [Open an issue](https://github.com/yourusername/caddy-proxy-manager/issues) or submit a PR!
[Open an issue](https://github.com/fuomag9/caddy-proxy-manager/issues) for feature requests.
---
## Contributing
We welcome contributions from the community! Here's how you can help:
Contributions welcome:
1. **Fork the repository**
2. **Create a feature branch** (`git checkout -b feature/amazing-feature`)
3. **Commit your changes** (`git commit -m 'Add amazing feature'`)
4. **Push to the branch** (`git push origin feature/amazing-feature`)
5. **Open a Pull Request**
### Development Guidelines
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
@@ -359,9 +279,6 @@ We welcome contributions from the community! Here's how you can help:
## Support
Need help? We're here for you:
- **Documentation:** Check this README and inline code comments
- **Issues:** [GitHub Issues](https://github.com/yourusername/caddy-proxy-manager/issues) for bugs and feature requests
- **Discussions:** [GitHub Discussions](https://github.com/yourusername/caddy-proxy-manager/discussions) for questions and ideas
@@ -385,8 +302,6 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
<div align="center">
Made with ❤️ by the Caddy Proxy Manager community
[⬆ back to top](#caddy-proxy-manager)
</div>