96 lines
3.0 KiB
Markdown
96 lines
3.0 KiB
Markdown
# 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 `CHARON_ACME_STAGING` environment variable (legacy `CPM_ACME_STAGING` still supported)
|
|
|
|
### 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 `CHARON_ACME_STAGING=true` environment variable for local development (legacy `CPM_ACME_STAGING` still supported)
|
|
|
|
### 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)
|
|
```bash
|
|
docker run -d \
|
|
-e CHARON_ACME_STAGING=true \
|
|
-p 8080:8080 \
|
|
ghcr.io/wikid82/charon:latest
|
|
```
|
|
|
|
### Production (Real Certificates)
|
|
```bash
|
|
docker run -d \
|
|
-p 8080:8080 \
|
|
ghcr.io/wikid82/charon: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
|