ClearProxy

A modern, web-based management interface for Caddy, focusing on reverse proxy configuration with automatic HTTPS.

Features

• 🌐 Easy management of proxy hosts
• 🔒 Automatic HTTPS via Caddy's built-in ACME client
• 🔐 Basic authentication support for proxied hosts
• ⚡ Modern, responsive UI built with SvelteKit
• 🛠️ Advanced configuration support with raw Caddyfile syntax
• 📊 Access logging and monitoring
• 🔄 Automatic database migrations

Documentation

Comprehensive documentation is available in the docs folder:

• Getting Started - Installation and initial setup
• User Guide - Comprehensive guide to using ClearProxy
• Proxy Hosts - Managing proxy hosts and domains
• Authentication - Setting up authentication for proxied hosts
• Advanced Configuration - Custom configurations for advanced features
• Troubleshooting - Common issues and solutions
• FAQ - Frequently asked questions

Quick Start

Using Docker (Recommended)

1. Create a new directory and download the docker-compose.yml:

mkdir clearproxy && cd clearproxy
curl -L https://raw.githubusercontent.com/foggymtndrifter/clearproxy/main/docker-compose.yml -o docker-compose.yml

2. Create required directories and configuration:

mkdir -p data/caddy/data data/caddy/config/caddy data/certificates logs

cat > data/caddy/config/caddy/caddy.json << 'EOF'
{
  "admin": {
    "listen": "0.0.0.0:2019",
    "enforce_origin": false,
    "origins": ["*"]
  },
  "apps": {
    "http": {
      "servers": {
        "srv0": {
          "listen": [":80"],
          "routes": []
        }
      }
    }
  }
}
EOF

3. Create or modify docker-compose.yml:

version: '3.8'

services:
  app:
    image: ghcr.io/${GITHUB_REPOSITORY:-foggymtndrifter/clearproxy}:latest
    container_name: clearproxy-app
    restart: unless-stopped
    ports:
      - '3000:3000'
    environment:
      - NODE_ENV=production
      - DATABASE_URL=file:/data/clearproxy.db
      - CADDY_API_URL=http://caddy:2019
    volumes:
      - ./data:/data
      - ./logs:/app/build/logs
    networks:
      - proxy-network
    depends_on:
      - caddy

  caddy:
    image: caddy:2-alpine
    container_name: clearproxy-caddy
    restart: unless-stopped
    command: caddy run --config /config/caddy/caddy.json
    environment:
      - CADDY_ADMIN_LISTEN=0.0.0.0:2019 # Required for admin API access
    security_opt:
      - no-new-privileges:true
    ports:
      - '80:80'
      - '443:443'
      - '2019:2019' # Admin API port (can be changed, e.g., "3019:2019")
    volumes:
      - ./data/caddy/data:/data
      - ./data/caddy/config:/config
      - ./data/certificates:/certificates
    networks:
      - proxy-network

networks:
  proxy-network:
    name: proxy-network
    driver: bridge

4. Start the application:

docker compose up -d

The application will be available at http://localhost:3000.

Local Development

See CONTRIBUTING.md for detailed setup instructions.

Configuration

The application uses SQLite for data storage and communicates with Caddy's admin API.

Environment Variables

• CADDY_API_URL: URL of Caddy's admin API (default: http://localhost:2019)
• DATABASE_URL: SQLite database connection URL (default: file:./clearproxy.db)
• LOG_LEVEL: Logging level (default: info)
• NODE_ENV: Environment mode (development or production)
• PORT: Application port (default: 3000)
• ORIGIN: The URL origin for the application (default: http://localhost)
• MIGRATIONS_PATH: Path to database migration files

Docker Architecture

The setup includes two containers:

1. ClearProxy App (clearproxy-app):

   • SvelteKit application
   • Business logic and UI
   • SQLite database management

2. Caddy Server (clearproxy-caddy):

   • Proxy operations
   • SSL/TLS certificate management
   • Admin API

Updating

To update to the latest version:

# Using Docker Compose
docker compose pull
docker compose up -d

Troubleshooting

If you encounter issues:

1. Check the logs:

docker compose logs app
docker compose logs caddy

2. Common issues:
   • Verify Caddy JSON configuration exists and is correct
   • Ensure required directories exist with proper permissions
   • Check Caddy admin API accessibility (port 2019)

For more detailed troubleshooting assistance, please see the Troubleshooting Guide.

Community

• GitHub Issues - Bug reports and feature requests
• GitHub Discussions - General questions and discussions
• Community chat (coming soon)

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Support the Project

If you find ClearProxy useful, consider buying me a coffee to support ongoing development!

License

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