Installation
Caddy Defender can be installed through multiple methods. Choose the one that best fits your workflow.
Docker (Recommended)
The easiest way to use Caddy Defender is with the pre-built Docker image.
Pull the Docker Image
Pull the latest Caddy Defender image from GitHub Container Registry:docker pull ghcr.io/jasonlovesdoggo/caddy-defender:latest
Create a Caddyfile
Create a Caddyfile with your configuration. Here’s a simple example:localhost:8080 {
defender block {
ranges openai deepseek
}
respond "Hello, human!"
}
Run the Container
Start Caddy with your configuration:docker run -d \
--name caddy \
-v /path/to/Caddyfile:/etc/caddy/Caddyfile \
-p 80:80 -p 443:443 \
ghcr.io/jasonlovesdoggo/caddy-defender:latest
Replace /path/to/Caddyfile with the actual path to your Caddyfile.
Verify Installation
Check that the container is running:Test your endpoint:curl http://localhost:8080
For production deployments, consider using Docker Compose or Kubernetes for better container orchestration.
Using xcaddy
Build a custom Caddy binary with the Defender plugin using xcaddy.
Install xcaddy
Install xcaddy using Go:go install github.com/caddyserver/xcaddy/cmd/xcaddy@latest
Requires Go 1.21 or later. Install Go from golang.org. Build Caddy with Defender Plugin
Build a custom Caddy binary with the Defender plugin:xcaddy build --with pkg.jsn.cam/caddy-defender
caddy binary in your current directory with the Defender plugin included.You can add multiple plugins in a single build:xcaddy build \
--with pkg.jsn.cam/caddy-defender \
--with github.com/mholt/caddy-ratelimit
Run Caddy
Use the built binary to run Caddy with your configuration:./caddy run --config Caddyfile
./caddy start --config Caddyfile
Verify the Plugin
Check that the Defender plugin is loaded:./caddy list-modules | grep defender
Download Pre-built Binary
Download Caddy with the Defender plugin pre-installed from the official Caddy download page.
Visit Caddy Download Page
Select Your Platform
Choose your operating system and architecture from the dropdown menus.
Download and Extract
Click Download and extract the archive:tar -xzf caddy_*.tar.gz
chmod +x caddy
Run Caddy
Run Caddy with your configuration:./caddy run --config Caddyfile
Verify Installation
Regardless of your installation method, verify that Caddy Defender is working:
Create a Test Caddyfile
:2015 {
defender block {
ranges private
}
respond "Success! Caddy Defender is working."
}
Run Caddy
caddy run --config Caddyfile
Test from Localhost
Test from localhost (which is in the private range):curl http://localhost:2015
403 Forbidden response, confirming Defender is blocking private IPs. System Service Installation
For production environments, install Caddy as a system service.
Linux (systemd)
# Copy binary to system path
sudo cp caddy /usr/bin/
# Create Caddy user
sudo groupadd --system caddy
sudo useradd --system --gid caddy --home-dir /var/lib/caddy --shell /usr/sbin/nologin caddy
# Create systemd service
sudo curl -o /etc/systemd/system/caddy.service \
https://raw.githubusercontent.com/caddyserver/dist/master/init/caddy.service
# Reload systemd and start Caddy
sudo systemctl daemon-reload
sudo systemctl enable --now caddy
macOS (launchd)
# Copy binary to system path
sudo cp caddy /usr/local/bin/
# Download and install launchd plist
sudo curl -o /Library/LaunchDaemons/com.caddyserver.caddy.plist \
https://raw.githubusercontent.com/caddyserver/dist/master/init/com.caddyserver.caddy.plist
# Start Caddy service
sudo launchctl load /Library/LaunchDaemons/com.caddyserver.caddy.plist
Upgrading
Regularly update Caddy Defender to get the latest IP ranges and security improvements.
Docker
docker pull ghcr.io/jasonlovesdoggo/caddy-defender:latest
docker stop caddy && docker rm caddy
# Run new container with same configuration
xcaddy
xcaddy build --with pkg.jsn.cam/caddy-defender
# Replace old binary with new one
Next Steps
Quickstart Guide
Create your first Caddy Defender configuration
Configuration
Learn about all configuration options