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. Once you have built a Coraza-enabled binary, there are no apt module packages or library conflicts to manage.
• 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

Vanilla Caddy does not understand the coraza_waf directive. Before any Caddyfile in this guide will load, you need a Caddy binary compiled with the Coraza WAF plugin. The current module path is github.com/corazawaf/coraza-caddy/v2 (v2 major version, current release v2.5.0).

Option A: Build with xcaddy

xcaddy build --with github.com/corazawaf/coraza-caddy/v2

This produces a caddy binary in the current directory that includes the Coraza module. Run ./caddy version to confirm.

Option B: Multi-stage Dockerfile

FROM caddy:builder AS builder
RUN xcaddy build --with github.com/corazawaf/coraza-caddy/v2

FROM caddy
COPY --from=builder /usr/bin/caddy /usr/bin/caddy

docker build -t caddy-coraza .

Alternatively, download a Coraza-enabled build from the Caddy download server (caddyserver.com/download, select the coraza-caddy package) or use a prebuilt Coraza image.

Loading the OWASP CRS

Every Caddyfile snippet below uses the load_owasp_crs subdirective inside the coraza_waf block. This registers the OWASP Core Rule Set embedded in the module, which is what makes the @coraza.conf-recommended, @crs-setup.conf.example, and @owasp_crs/*.conf macro includes resolve. Without load_owasp_crs, those @-prefixed includes fail because the referenced files are not registered.

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:
basic_auth {
    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.