Charon/ACME_STAGING_IMPLEMENTATION.md

ACME Staging Implementation Summary

What Was Added

Added support for Let's Encrypt staging environment to prevent rate limiting during development and testing.

Changes Made

1. Configuration (backend/internal/config/config.go)

• Added ACMEStaging bool field to Config struct
• Reads from CPM_ACME_STAGING environment variable

2. Caddy Manager (backend/internal/caddy/manager.go)

• Added acmeStaging bool field to Manager struct
• Updated NewManager() to accept acmeStaging parameter
• Passes acmeStaging to GenerateConfig()

3. Config Generation (backend/internal/caddy/config.go)

• Updated GenerateConfig() signature to accept acmeStaging bool
• When acmeStaging=true:
  • Sets ca field to https://acme-staging-v02.api.letsencrypt.org/directory
  • Applies to both "letsencrypt" and "both" SSL provider modes

4. Route Registration (backend/internal/api/routes/routes.go)

• Passes cfg.ACMEStaging to caddy.NewManager()

5. Docker Compose (docker-compose.local.yml)

• Added CPM_ACME_STAGING=true environment variable for local development

6. Tests

• Updated all test files to pass new acmeStaging parameter
• Added TestGenerateConfig_ACMEStaging() to verify behavior
• All tests pass ✅

7. Documentation

• Created /docs/acme-staging.md - comprehensive guide
• Updated /docs/getting-started.md - added environment variables section
• Explained rate limits, staging vs production, and troubleshooting

Usage

Development (Avoid Rate Limits)

docker run -d \
  -e CPM_ACME_STAGING=true \
  -p 8080:8080 \
  ghcr.io/wikid82/cpmp:latest

Production (Real Certificates)

docker run -d \
  -p 8080:8080 \
  ghcr.io/wikid82/cpmp:latest

Verification

Container logs confirm staging is active:

"ca":"https://acme-staging-v02.api.letsencrypt.org/directory"

Benefits

1. No Rate Limits: Test certificate issuance without hitting Let's Encrypt limits
2. Safe Testing: Won't affect production certificate quotas
3. Easy Toggle: Single environment variable to switch modes
4. Default Production: Staging must be explicitly enabled
5. Well Documented: Clear guides for users and developers

Test Results

• ✅ All backend tests pass (go test ./...)
• ✅ Config generation tests verify staging CA is set
• ✅ Manager tests updated and passing
• ✅ Handler tests updated and passing
• ✅ Integration verified in running container

Files Modified

• backend/internal/config/config.go
• backend/internal/caddy/config.go
• backend/internal/caddy/manager.go
• backend/internal/api/routes/routes.go
• backend/internal/caddy/config_test.go
• backend/internal/caddy/manager_test.go
• backend/internal/caddy/client_test.go
• backend/internal/api/handlers/proxy_host_handler_test.go
• docker-compose.local.yml

Files Created

• docs/acme-staging.md - User guide
• ACME_STAGING_IMPLEMENTATION.md - This summary