Caddy Server Deployment Guide
Prerequisites
- Go 1.25.0 or newer - Required for building from source
- Operating System - Caddy runs on any platform with no external dependencies (not even libc)
- Administrator privileges (optional) - Required for binding to low ports (ports < 1024) on Unix-like systems
Installation
Quick Start (Recommended)
The simplest way to get started is to download Caddy from GitHub Releases and place the executable file in your PATH.
Building from Source
# Clone the repository
$ git clone "https://github.com/caddyserver/caddy.git"
$ cd caddy/cmd/caddy/
# Build the binary
$ go build
Note: Building this way will not embed proper version information. For development with version information and/or plugins, follow the instructions in the next section.
For Development with Version Information
To build with proper version information and plugins, you'll need to use the appropriate build flags and configuration. Refer to the Caddy documentation for detailed instructions on building with plugins and version information.
Configuration
Environment Variables
- CADDY_ADMIN - Overrides the default admin address. Can be used by packagers to change the default admin address to something more appropriate for that platform.
Configuration Files
Caddy uses native JSON configuration, but supports various config adapters for different formats:
- Caddyfile - Easy-to-use configuration format
- JSON API - Dynamic configuration through API
- Config adapters - Convert various inputs into Caddy JSON
TLS Configuration
Caddy provides automatic HTTPS by default with:
- ZeroSSL and Let's Encrypt for public names
- Fully-managed local CA for internal names & IPs
- Multi-issuer fallback
- Encrypted ClientHello (ECH) support
Build & Run
Local Development
# Build the binary
$ go build
# Run Caddy (may require sudo for low ports)
$ ./caddy
Production
For production deployments, consider:
- Binary installation - Download pre-built binaries from releases
- Service management - Use systemd, launchd, or similar service managers
- Configuration management - Use environment variables or config files
Admin API
Caddy has a built-in admin API for runtime management:
# Default admin address (can be overridden)
$ CADDY_ADMIN="localhost:2019" ./caddy
Deployment
Platform Recommendations
Based on Caddy's Go-based architecture and zero-dependency nature, suitable deployment platforms include:
Cloud Platforms
- AWS - EC2, ECS, Lambda (via container)
- Google Cloud - Compute Engine, Cloud Run
- Azure - Virtual Machines, Container Instances
- DigitalOcean - Droplets, App Platform
Container Platforms
# Build Docker container
$ docker build -t caddy .
# Run container
$ docker run -p 80:80 -p 443:443 caddy
PaaS Platforms
- Heroku - Via container or buildpack
- Render - Web service deployment
- Railway - Container deployment
Self-Hosting
- VPS - Any Linux VPS provider
- Bare metal - Direct hardware deployment
- Home server - Local network deployment
Troubleshooting
Common Issues
Port Binding Issues
- Problem: "permission denied" when binding to ports < 1024
- Solution: Run with elevated privileges or use higher ports (e.g., 8080, 8443)
TLS Certificate Issues
- Problem: Certificate acquisition failures
- Solution: Check DNS configuration, ensure proper rate limits, verify network connectivity to ACME servers
Configuration Errors
- Problem: Invalid configuration syntax
- Solution: Validate configuration using Caddy's config adapters or JSON schema
Performance Issues
- Problem: High memory usage or slow response times
- Solution: Monitor resource usage, adjust worker settings, consider load balancing
Debug Mode
Enable debug logging for troubleshooting:
$ CADDY_DEBUG=true ./caddy
Health Checks
Monitor Caddy's health through the admin API or standard HTTP endpoints.
Community Support
- Documentation: caddyserver.com/docs
- Community Forum: caddy.community
- GitHub Issues: github.com/caddyserver/caddy/issues
Performance Monitoring
Caddy includes built-in metrics and profiling:
- Prometheus metrics - Available through the admin API
- pprof endpoints - For performance profiling
- Expvar - Runtime statistics
This guide provides a comprehensive overview of deploying and using Caddy server. For detailed configuration options and advanced features, refer to the official documentation.