caddy-cloudflare-cli

Caddy Cloudflare CLI

A powerful CLI tool for setting up and managing Cloudflare DNS records with Caddy reverse proxy. Easily deploy local services with public domains, automate DNS configuration, and manage SSL certificates using Cloudflare's API.

Features

• 🚀 Create and manage Cloudflare DNS records with ease
• 🔒 Automatic SSL certificate provisioning via Caddy and Cloudflare
• 🌐 Expose local services to the internet in seconds
• 🛡️ Leverage Cloudflare's security and CDN benefits
• 🔄 Simple commands to deploy, list, and remove domains

Installation

# Install with pip
pip install caddy-cloudflare-cli

# Or install with development dependencies
pip install caddy-cloudflare-cli[dev]

Cloudflare Setup Guide

Before using this tool, you'll need a Cloudflare account and domain. Follow these steps:

1. Register a Domain

If you don't already have a domain:

• Purchase a domain from any domain registrar (Namecheap, GoDaddy, etc.)
• We recommend choosing a domain registrar based on price and their ease of changing nameservers

2. Add Domain to Cloudflare

• Create a Cloudflare account if you don't have one
• Log in to Cloudflare and click "Add a Site"
• Enter your domain name and click "Add Site"
• Select a plan (the Free plan works fine for this tool)
• Cloudflare will scan for existing DNS records

3. Update Nameservers

• Cloudflare will provide you with nameservers (e.g., cruz.ns.cloudflare.com and tim.ns.cloudflare.com)
• Go to your domain registrar's website
• Find the nameserver settings for your domain
• Replace the current nameservers with Cloudflare's nameservers
• Save the changes (propagation can take up to 24 hours)

4. Create API Tokens

For the most secure setup, create dedicated API tokens:

• Go to your Cloudflare dashboard
• Navigate to "My Profile" → "API Tokens"
• Click "Create Token"
• Choose "Create Custom Token"
• Give your token a name (e.g., "Caddy DNS Token")
• Under "Permissions", add:
  • Zone - DNS - Edit
• Under "Zone Resources", select:
  • Include - Specific zone - Your domain
• Click "Continue to Summary" and then "Create Token"
• Copy the token value (you won't be able to see it again!)

Usage

Initial Setup

# Initialize configuration
caddy-cloudflare init

Follow the interactive prompts to configure your Cloudflare credentials and domain.

Install Caddy

# Install Caddy locally
caddy-cloudflare install

# Or install Caddy system-wide (requires sudo)
sudo caddy-cloudflare install --system

Deploy a Service

# Deploy with interactive prompts
caddy-cloudflare deploy

# Deploy with specific options
caddy-cloudflare deploy --subdomain myapp --port 3000

# Using a custom IP (instead of auto-detection)
caddy-cloudflare deploy --ip 203.0.113.1

Manage Deployments

# List all deployments
caddy-cloudflare list

# Show all DNS records (not just deployments)
caddy-cloudflare list --all

# Delete a deployment
caddy-cloudflare delete myapp

Proxy Management

# Start the Caddy proxy
caddy-cloudflare proxy start

# Check proxy status
caddy-cloudflare proxy status

# Stop the proxy
caddy-cloudflare proxy stop

# Reload proxy configuration
caddy-cloudflare proxy reload

Troubleshooting

# Run diagnostic checks
caddy-cloudflare debug

Advanced Usage

Using Environment Variables

You can use environment variables instead of storing credentials in config files:

# API Token method (recommended)
export CLOUDFLARE_API_TOKEN="your-api-token"

# Least privilege method (recommended)
export CLOUDFLARE_ZONE_TOKEN="your-zone-token"
export CLOUDFLARE_DNS_TOKEN="your-dns-token"

# Global API key method (legacy)
export CLOUDFLARE_API_KEY="your-global-api-key"
export CLOUDFLARE_EMAIL="[e-mail]"

# Domain configuration
export CLOUDFLARE_DOMAIN="yourdomain.com"

Contributing

Contributions are welcome! Here's how you can contribute:

• Fork the repository
• Create a feature branch: git checkout -b feature/my-new-feature
• Commit your changes: git commit -am 'Add some feature'
• Push to the branch: git push origin feature/my-new-feature
• Submit a pull request

Development Setup

# Clone repository
git clone https://github.com/yourusername/caddy-cloudflare-cli.git
cd caddy-cloudflare-cli

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

Areas for Contribution

We're especially interested in contributions for:

• New DNS Providers: Add support for more DNS providers beyond Cloudflare
• New Proxy Providers: Add support for additional reverse proxy solutions
• Bug Fixes: Help identify and fix bugs
• Documentation: Improve documentation and examples
• Testing: Add more tests and improve test coverage

Creating Issues

If you find a bug or want to request a feature, please create an issue:

## Description
A clear description of the issue or feature request

## Steps to Reproduce (for bugs)
1. Step 1
2. Step 2
3. ...

## Expected Behavior
What you expected to happen

## Actual Behavior
What actually happened

## Environment
- OS: [e.g., Ubuntu 22.04]
- Python version: [e.g., 3.11.2]
- Package version: [e.g., 0.1.0]

TODO

• Add support for wedos.cz WAPI DNS provider
• Implement direct Cloudflare Tunnel support
• Add support for more complex Caddy configurations
• Create Docker container for easier deployment
• Implement concurrent multi-domain management

License

This project is licensed under the GNU General Public License v3.0.