Migrate from Apache to Caddy + Coraza WAF

Valid reasons to migrate:

• Simpler configuration: Apache's VirtualHost + .htaccess + mod_rewrite stack is powerful but complex. A Caddyfile for the same setup is typically one-third the size.
• Automatic HTTPS: no more certbot, no more cron jobs, no more expired certificate emergencies. Caddy manages TLS certificates automatically.
• Modern WAF engine: while Apache's ModSecurity integration is the most mature, Coraza is a modern Go reimplementation that runs the same CRS rules with zero C dependencies.
• Docker-native: Caddy + Coraza runs as a single container. No module compilation, no apt packages, no library conflicts.
• Performance: Apache's prefork/worker model is battle-tested but Caddy's event-driven architecture handles concurrent connections with less memory overhead.

Do not migrate if:

• You rely heavily on mod_php (though php_fastcgi is a clean alternative)
• You have hundreds of .htaccess files across many directories
• Your team has deep Apache expertise and the current setup works well
• You use Apache-specific modules (mod_perl, mod_python, mod_jk) with no alternatives

Document everything before you start:

1. List all sites and VirtualHosts

# List enabled sites ls /etc/apache2/sites-enabled/ # or on CentOS/RHEL: ls /etc/httpd/conf.d/
# Find all ServerName entries grep -rh "ServerName\|ServerAlias" /etc/apache2/sites-enabled/ | sort -u

2. Find all .htaccess files

# This is critical - Caddy does not support .htaccess find /var/www -name ".htaccess" -exec echo "=== {} ===" \; -exec cat {} \;

Save this output. Every .htaccess rule needs to move into the Caddyfile.

3. Document proxy targets and backend services

grep -rh "ProxyPass\|ProxyPassReverse" /etc/apache2/sites-enabled/ | sort -u

4. Check for special modules

# List loaded Apache modules apache2ctl -M 2>/dev/null || httpd -M 2>/dev/null
# Check for modules that need special handling # mod_php, mod_rewrite, mod_security2, mod_ssl, mod_proxy, mod_headers

5. Note PHP setup

# Check if using mod_php or PHP-FPM apache2ctl -M 2>/dev/null | grep php # If php is listed, you are using mod_php # Caddy uses PHP-FPM instead - you will need to set this up

This is the biggest difference between Apache and Caddy migrations (Nginx does not use .htaccess, so this step does not apply to Nginx migrations).

Common .htaccess patterns and their Caddyfile equivalents:

# .htaccess: Force HTTPS RewriteEngine On RewriteCond %{HTTPS} off RewriteRule (.*) https://%{HTTP_HOST}%{REQUEST_URI} [R=301,L] # Caddy: automatic (just use a domain name)
# .htaccess: Deny directory listing Options -Indexes # Caddy: file_server (without browse flag)
# .htaccess: Block specific files <FilesMatch "\.(env|git|sql)$"> Require all denied </FilesMatch> # Caddy: @blocked path *.env *.git *.sql respond @blocked 403
# .htaccess: Custom error pages ErrorDocument 404 /404.html # Caddy: handle_errors { rewrite * /{err.status_code}.html file_server }
# .htaccess: Password protection AuthType Basic AuthName "Restricted" AuthUserFile /path/.htpasswd Require valid-user # Caddy: basicauth { user $2a$14$... (bcrypt hash) }
# .htaccess: WordPress pretty permalinks RewriteRule ^index\.php$ - [L] RewriteCond %{REQUEST_FILENAME} !-f RewriteCond %{REQUEST_FILENAME} !-d RewriteRule . /index.php [L] # Caddy: php_fastcgi unix//run/php/php-fpm.sock { try_files {path} /index.php }

If your Apache setup uses mod_php, you need to switch to PHP-FPM. This is actually the recommended approach even in Apache for better performance.

Install PHP-FPM:

sudo apt install php-fpm # or for specific version: sudo apt install php8.3-fpm

Configure Caddy for PHP:

example.com { coraza_waf { load_owasp_crs directives ` Include @coraza.conf-recommended Include @crs-setup.conf.example Include @owasp_crs/*.conf SecRuleEngine On ` }
root * /var/www/html php_fastcgi unix//run/php/php-fpm.sock file_server }

The php_fastcgi directive handles index.php routing, PATH_INFO, and all the PHP-specific headers automatically. For WordPress, this single directive replaces the entire .htaccess mod_rewrite block.

Use the directive mapping table from our Apache WAF Protection guide to convert each VirtualHost. Inline any .htaccess rules from the previous step.

Example conversion of a typical Apache VirtualHost:

Before (Apache):

<VirtualHost *:80> ServerName example.com Redirect permanent / https://example.com/ </VirtualHost>
<VirtualHost *:443> ServerName example.com DocumentRoot /var/www/html
SSLEngine on SSLCertificateFile /etc/letsencrypt/live/example.com/fullchain.pem SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem
<IfModule security2_module> SecRuleEngine On IncludeOptional /etc/modsecurity/crs/crs-setup.conf IncludeOptional /etc/modsecurity/crs/rules/*.conf </IfModule>
Header set X-Content-Type-Options nosniff Header set X-Frame-Options DENY
<Directory /var/www/html> AllowOverride All Require all granted </Directory> </VirtualHost>

After (Caddy):

{ order coraza_waf first }
example.com { coraza_waf { load_owasp_crs directives ` Include @coraza.conf-recommended Include @crs-setup.conf.example Include @owasp_crs/*.conf SecRuleEngine On ` }
root * /var/www/html file_server encode gzip
header { X-Content-Type-Options nosniff X-Frame-Options DENY } }

The HTTP-to-HTTPS redirect, SSL config, and certbot integration all disappear. Caddy handles them automatically.

The testing, cutover, and rollback process is the same as for Nginx migrations:

1. Validate Caddyfile syntax: caddy validate --config Caddyfile --adapter caddyfile
2. Run in staging: test every site against your pre-migration inventory
3. Test WAF: verify attacks are blocked and legitimate traffic passes
4. Test PHP: if using PHP, verify all pages render, forms submit, and uploads work
5. Gradual cutover: DNS-based (lower TTL first), load balancer split, or per-site migration
6. Keep Apache running: do not decommission until Caddy has been stable for at least a week

Rollback:

Point traffic back to Apache (DNS change or load balancer switch). Apache should still be running and ready to serve. The rollback takes under 2 minutes.

For the detailed cutover strategies, see the Nginx migration guide. The process is identical.