Charon/docs/plans/archive/caddy_upgrade_plan.md

Caddy v2.11.0-beta.2 Upgrade Plan

Created: 2026-01-06 Risk Level: LOW Estimated Duration: 30-45 minutes

Overview

Upgrade Caddy from v2.10.2 to v2.11.0-beta.2 to gain:

• Built-in quic-go v0.58.0 (removes need for CVE patch)
• Built-in smallstep/certificates v0.29.0 (removes need for manual patch)
• Various bug fixes and enhancements

---

Phase 1: Dockerfile Changes

File: /projects/Charon/Dockerfile

1.1 Update Caddy Version

Change line ~17:

# FROM:
ARG CADDY_VERSION=2.10.2

# TO:
ARG CADDY_VERSION=2.11.0-beta.2

1.2 Remove Obsolete Dependency Patches

In the Caddy builder stage (~line 108-115), remove these patches that are now included upstream:

# REMOVE these lines:
# renovate: datasource=go depName=github.com/quic-go/quic-go
go get github.com/quic-go/quic-go@v0.57.1; \
# renovate: datasource=go depName=github.com/smallstep/certificates
go get github.com/smallstep/certificates@v0.29.0; \

KEEP this patch (still required):

# renovate: datasource=go depName=github.com/expr-lang/expr
go get github.com/expr-lang/expr@v1.17.7; \

1.3 Update Comments

Update the version comment block (~lines 9-17) to reflect the beta version.

---

Phase 2: Build Verification

2.1 Build Docker Image

docker build --no-cache -t charon:caddy-upgrade-test .

2.2 Verify Caddy Starts

docker run --rm charon:caddy-upgrade-test caddy version

Expected output should show v2.11.0-beta.2.

2.3 Verify Plugins Load

docker run --rm charon:caddy-upgrade-test caddy list-modules | grep -E "security|coraza|crowdsec|maxmind|rate"

Expected plugins:

• http.handlers.crowdsec
• http.handlers.waf (coraza)
• http.matchers.maxminddb
• http.handlers.rate_limit
• security (caddy-security)

---

Phase 3: Testing

3.1 Backend Unit Tests

# Using existing task
# Task: "Test: Backend Unit Tests"
cd backend && go test ./... -v

3.2 Integration Tests

# Start the container
docker compose -f .docker/compose/docker-compose.local.yml up -d

# Run Coraza WAF tests
# Task: "Integration: Coraza WAF"

# Run CrowdSec tests
# Task: "Integration: CrowdSec"

3.3 Manual Verification Checklist

• Caddy health endpoint responds: curl http://localhost:2019/config/
• Config reload works: curl -X POST http://localhost:2019/load -H "Content-Type: application/json" -d @test-config.json
• HTTPS/certificate automation works (if applicable)
• WAF rules trigger correctly
• CrowdSec bouncer integration works

---

Phase 4: Documentation

4.1 Update CHANGELOG.md

Add entry under next release:

### Changed
- Upgraded Caddy from v2.10.2 to v2.11.0-beta.2
- Removed manual quic-go and smallstep/certificates patches (now included upstream)

4.2 Update Version References

Search and update any version references:

grep -r "2.10.2" docs/

---

Rollback Plan

If issues are encountered:

1. Revert ARG CADDY_VERSION to 2.10.2
2. Restore the removed dependency patches
3. Rebuild the image

---

Post-Upgrade Monitoring

After deployment:

• Monitor Caddy logs for errors: docker logs -f <container> 2>&1 | grep -i caddy
• Check certificate renewal works
• Verify no performance regressions