From 0a2a5ee5f1aad629ab2c9dc13dfb6254cbfeac4a Mon Sep 17 00:00:00 2001 From: fuomag9 <1580624+fuomag9@users.noreply.github.com> Date: Tue, 4 Nov 2025 00:11:01 +0100 Subject: [PATCH] Update README.md --- README.md | 353 ++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 225 insertions(+), 128 deletions(-) diff --git a/README.md b/README.md index d0619941..3c105596 100644 --- a/README.md +++ b/README.md @@ -1,199 +1,296 @@ +
+ # Caddy Proxy Manager -[caddyproxymanager.com](https://caddyproxymanager.com) +### Modern Web UI for Caddy Server -> A modern web UI for Caddy. Manage reverse proxies, redirects, maintenance pages, certificates, and access lists with a single admin account. +[![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)](https://github.com/yourusername/caddy-proxy-manager) +[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE) +[![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/yourusername/caddy-proxy-manager/issues) • [Request Feature](https://github.com/yourusername/caddy-proxy-manager/issues) + +
--- -## Why Use It? +## Welcome! 👋 -- Point-and-click management of Caddy reverse proxies and TLS -- Works out of the box with Docker Compose or a local Node.js setup -- Keeps a full audit trail of every configuration change -- Admin-first: no multi-tenant complexity, but hardened defaults everywhere +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.** --- -## Quick Start (2 Minutes) +## Why Caddy Proxy Manager? -1. **Install dependencies** +### 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 - ```bash - npm install - ``` +### 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 -2. **Copy env file** +### 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 Prisma with TypeScript throughout - ```bash - cp .env.example .env - ``` +--- -3. **Set credentials** +## Quick Start - ```env - ADMIN_USERNAME=your-admin - ADMIN_PASSWORD=your-strong-password - SESSION_SECRET=$(openssl rand -base64 32) - ``` +### Docker Compose (Recommended) -4. **Run the app** - - ```bash - npm run dev - ``` - -5. **Login** - - - Visit `http://localhost:3000/login` - - Enter your credentials (login attempts are rate-limited; rest a few minutes after five failures) - -### Docker Compose? +Get up and running in 2 minutes with our Docker setup: ```bash +# 1. Clone the repository +git clone https://github.com/yourusername/caddy-proxy-manager.git +cd caddy-proxy-manager + +# 2. Configure your environment cp .env.example .env -# edit .env with secure ADMIN_* values + +# 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 docker compose up -d ``` -The stack launches: +**What you get:** +- `web` – Next.js application server with SQLite database +- `caddy` – Custom Caddy build with Cloudflare DNS and Layer4 modules -- `web` – Next.js standalone server + SQLite at `/app/data` -- `caddy` – xcaddy build with Cloudflare DNS & layer4 modules +**Data persistence:** +- `./data` → Application database and imported certificates +- `./caddy-data` → ACME certificates and storage +- `./caddy-config` → Caddy runtime configuration -Volumes: +### Local Development -- `./data` → `/app/data` (SQLite database and imported certs) -- `./caddy-data` (ACME storage) -- `./caddy-config` (Caddy runtime config) +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 +npm run dev +``` + +Visit `http://localhost:3000/login` and sign in with your credentials. + +**Note:** Login attempts are rate-limited to 5 tries per 5 minutes. After repeated failures, wait 15 minutes before trying again. --- -## What You Get +## Features -- **Next.js 16 App Router** – hybrid server/client rendering, server actions, and streaming layouts -- **Material UI** – responsive dark-themed dashboard with polished defaults -- **Caddy integration** – generates JSON and pushes it directly to the Caddy admin API for proxies, redirects, and dead/maintenance responses -- **Certificate lifecycle** – manage ACME (Cloudflare DNS-01) or import PEM certificates; certificates written to disk with restrictive permissions -- **Access control** – bcrypt-backed HTTP basic-auth lists with assignment to proxy hosts -- **Observability** – built-in audit log records actor, action, and summary for every change -- **Security defaults** – strict session secret enforcement, mandatory credential rotation in production, HSTS injection for managed hosts, login throttling, and admin-only mutations +### 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** | Request ACME-managed certificates or import custom PEM files | +| **Settings** | Configure primary domain, ACME email, and Cloudflare DNS automation | +| **Audit Log** | Review chronological feed of all administrative actions | + +### 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 +- **Prisma ORM** – Type-safe database access with automatic 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 --- -## Architecture Overview +## Configuration + +### Environment Variables + +| Variable | Description | Default | Required | +|----------|-------------|---------|----------| +| `ADMIN_USERNAME` | Admin login username | `admin` (dev only) | Yes (production) | +| `ADMIN_PASSWORD` | Admin password (min 12 chars with letters & numbers) | `admin` (dev only) | Yes (production) | +| `SESSION_SECRET` | 32+ character string for session signing | - | Yes | +| `BASE_URL` | Public URL of the dashboard | `http://localhost:3000` | No | +| `CADDY_API_URL` | Caddy Admin API endpoint | `http://caddy:2019` | No | +| `DATABASE_PATH` | SQLite file path | `/app/data/caddy-proxy-manager.db` | No | +| `PRIMARY_DOMAIN` | Default domain for Caddy config | `caddyproxymanager.com` | No | + +**Production Security Requirements:** +- `ADMIN_PASSWORD` must be 12+ characters with both letters and numbers +- `SESSION_SECRET` must be 32+ characters and not a default value +- Default credentials (`admin`/`admin`) are automatically rejected + +--- + +## Architecture ``` -. -├── app/ # Next.js App Router (layouts, routes, server actions) -│ ├── (auth)/ # Login experience -│ ├── (dashboard)/ # Dashboard layout, feature modules, client renderers -│ ├── api/ # NextAuth handlers and health probe +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 # MUI theme provider -├── src/ -│ └── lib/ # Prisma client, domain models, Caddy config builder, helpers -├── prisma/ # Prisma schema +│ └── providers.tsx # Theme and context providers +├── src/lib/ # Core business logic +│ ├── models/ # Database models and operations +│ ├── caddy/ # Caddy config generation +│ └── auth/ # Authentication helpers +├── prisma/ # Database schema and migrations ├── docker/ -│ ├── web/ # Next.js production image -│ └── caddy/ # xcaddy build with Cloudflare + layer4 modules -├── docker-compose.yml # Sample two-container deployment (Next.js + Caddy) -└── data/ # Runtime SQLite database and certificate output +│ ├── web/ # Next.js production Dockerfile +│ └── caddy/ # Custom Caddy build (xcaddy + modules) +├── docker-compose.yml # Production deployment stack +└── data/ # Runtime data (SQLite + certificates) ``` -### Dashboard Surface - -| Module | Purpose | -| --- | --- | -| Proxy Hosts | Configure HTTP(S) reverse proxies, upstream pools, headers, and Authentik forward auth support | -| Redirects | Define 301/302 redirects with optional query preservation | -| Dead Hosts | Serve branded maintenance responses with custom status codes | -| Access Lists | Create & assign HTTP basic-auth user lists | -| Certificates | Request ACME-managed or import custom PEM certificates | -| Settings | Configure primary domain, ACME email, and Cloudflare DNS automation | -| Audit Log | Review a chronological feed of administrative actions | - --- -## Configuration Reference +## Security Features -| Variable | Description | Default | -| --- | --- | --- | -| `ADMIN_USERNAME` | Admin login username | `admin` (development only) | -| `ADMIN_PASSWORD` | Admin login password | `admin` (development only) | -| `SESSION_SECRET` | 32+ char string for JWT/session signing | _required_ | -| `BASE_URL` | Public URL for the dashboard | `http://localhost:3000` | -| `CADDY_API_URL` | Internal Caddy admin API endpoint | `http://caddy:2019` (production container) | -| `DATABASE_PATH` | SQLite file path | `/app/data/caddy-proxy-manager.db` | -| `PRIMARY_DOMAIN` | Default domain for generated Caddy config | `caddyproxymanager.com` | +We take security seriously. Here's what's built-in: -⚠️ **Production deployments must override `ADMIN_USERNAME`, `ADMIN_PASSWORD`, and `SESSION_SECRET`.** +- **Session Secret Enforcement** – Production requires strong, unique session secrets +- **Credential Validation** – Default credentials rejected; minimum complexity enforced +- **Login Throttling** – IP + username based rate limiting (5 attempts / 5 minutes) +- **Admin-Only Mutations** – All configuration changes require admin privileges +- **Certificate Protection** – Imported certificates stored with `0600` permissions +- **Audit Trail** – Immutable log of all administrative actions +- **HSTS Headers** – Strict-Transport-Security automatically applied to managed hosts +- **Secret Redaction** – API tokens never rendered back to the browser ---- - -## Project Status - -- **Deployment model:** single administrative user (configured via environment variables) -- **Authentication:** credentials flow rate-limited to 5 attempts / 5 minutes with a 15 minute cooldown after repeated failures -- **Authorization:** all mutating actions require admin privileges; read-only pages stay accessible to the authenticated session -- **Secrets management:** Cloudflare API tokens are accepted through the UI but never rendered back to the browser; existing tokens can be revoked explicitly -- **Known limitation:** Imported certificates are stored in SQLite without encryption (planned improvement) +**Known Limitations:** +- Imported certificate keys stored in SQLite without encryption (planned enhancement) +- In-memory rate limiting (requires Redis/Memcached for multi-instance deployments) --- ## Cloudflare DNS Automation -- Provide a Cloudflare API token with `Zone.DNS:Edit` permissions. -- The token field is rendered as a password input and never pre-filled. -- To revoke a stored token, select **Remove existing token** and submit. -- Zone ID / Account ID fields are optional but recommended for multi-zone setups. -- Managed certificates rely on valid credentials; otherwise, import PEMs manually. +To enable automatic SSL certificates with Cloudflare DNS-01 challenges: + +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 + +**To revoke a token:** Select "Remove existing token" in Settings and submit. --- -## Security Posture +## Development -- **Session Secret Enforcement:** Production boots only when `SESSION_SECRET` is strong and not a known placeholder. -- **Admin Credential Guardrails:** Default credentials rejected at runtime; production requires 12+ char password with letters & numbers. -- **Login Throttling:** Per-IP+username throttling (5 attempts / 5 minutes, 15 minute lockout). -- **Admin-Only Mutations:** All server actions that modify state require `requireAdmin()`. -- **Certificate Handling:** Imported certificates and keys are projected to disk with `0600` permissions; certificate directory forced to `0700`. _Note: database storage for imported key material is not yet encrypted._ -- **Audit Trail:** Every mutation logs actor/action/summary to SQLite. -- **Transport Security:** HSTS (`Strict-Transport-Security: max-age=63072000`) applied to managed hosts by default. +### Available Scripts + +| Command | Description | +|---------|-------------| +| `npm run dev` | Start development server with hot reload | +| `npm run build` | Create optimized production build | +| `npm start` | Run production server | +| `npm run typecheck` | Run TypeScript type checking | + +### Development Notes + +- **Database:** Prisma manages schema migrations. Run `npx prisma db push` to sync changes. +- **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. --- -## Scripts +## Roadmap -| Command | Purpose | -| --- | --- | -| `npm run dev` | Start Next.js in development mode | -| `npm run build` | Create production build | -| `npm start` | Run the production output | -| `npm run typecheck` | TypeScript project check | +We're actively working on these improvements: -> `npm run lint` is intentionally omitted until the lint pipeline is finalized for this workspace. +- [ ] Encrypted storage for imported certificate private keys +- [ ] Redis/Memcached integration for distributed rate limiting +- [ ] Multi-user support with role-based access control +- [ ] Additional DNS providers (Namecheap, Route53, etc.) +- [ ] Metrics and monitoring dashboard +- [ ] Backup and restore functionality +- [ ] API for programmatic configuration + +Have ideas? [Open an issue](https://github.com/yourusername/caddy-proxy-manager/issues) or submit a PR! --- -## Development Notes +## Contributing -- Prisma manages the SQLite schema. `npx prisma db push` runs during builds and entrypoint start. -- Caddy configuration is rebuilt on each mutation and pushed via the admin API; failures are surfaced to the UI with actionable errors. -- Login throttling state is kept in-memory per Node process; scale-out deployments should front the app with a shared cache (Redis/Memcached) for consistent limiting across replicas. -- The project currently supports a single administrator; introducing multi-role access will require revisiting authorization logic. +We welcome contributions from the community! Here's how you can help: + +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 + +- 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 --- -## Roadmap & Known Gaps +## Support -- Encrypt imported certificate material before persistence. -- Shared rate-limiting store for horizontally scaled deployments. -- Non-admin roles with scoped permissions. -- Additional DNS providers for managed certificates. +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 --- ## License -MIT License © Caddy Proxy Manager contributors +This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. + +--- + +## Acknowledgments + +- **[Caddy Server](https://caddyserver.com/)** – The amazing web server that powers this project +- **[Next.js](https://nextjs.org/)** – React framework for production +- **[Material UI](https://mui.com/)** – Beautiful React components +- **[Prisma](https://www.prisma.io/)** – Next-generation ORM + +--- + +
+ +Made with ❤️ by the Caddy Proxy Manager community + +[⬆ back to top](#caddy-proxy-manager) + +