134 lines
4.5 KiB
Markdown
134 lines
4.5 KiB
Markdown
# SmartProxy ACME Simplification Plan
|
|
|
|
## Overview
|
|
This plan addresses the certificate acquisition confusion in SmartProxy v19.0.0 and proposes simplifications to make ACME configuration more intuitive.
|
|
|
|
## Current Issues
|
|
1. ACME configuration placement is confusing (route-level vs top-level)
|
|
2. SmartAcme initialization logic is complex and error-prone
|
|
3. Documentation doesn't clearly explain the correct configuration format
|
|
4. Error messages like "SmartAcme not initialized" are not helpful
|
|
|
|
## Proposed Simplifications
|
|
|
|
### 1. Support Both Configuration Styles
|
|
- [x] Reread CLAUDE.md before starting implementation
|
|
- [x] Accept ACME config at both top-level and route-level
|
|
- [x] Use top-level ACME config as defaults for all routes
|
|
- [x] Allow route-level ACME config to override top-level defaults
|
|
- [x] Make email field required when any route uses `certificate: 'auto'`
|
|
|
|
### 2. Improve SmartAcme Initialization
|
|
- [x] Initialize SmartAcme when top-level ACME config exists with email
|
|
- [x] Initialize SmartAcme when any route has `certificate: 'auto'`
|
|
- [x] Provide clear error messages when initialization fails
|
|
- [x] Add debug logging for ACME initialization steps
|
|
|
|
### 3. Simplify Certificate Configuration
|
|
- [x] Create helper method to validate ACME configuration
|
|
- [x] Auto-detect when port 80 is needed for challenges
|
|
- [x] Provide sensible defaults for ACME settings
|
|
- [x] Add configuration examples in documentation
|
|
|
|
### 4. Update Documentation
|
|
- [x] Create clear examples for common ACME scenarios
|
|
- [x] Document the configuration hierarchy (top-level vs route-level)
|
|
- [x] Add troubleshooting guide for common certificate issues
|
|
- [x] Include migration guide from v18 to v19
|
|
|
|
### 5. Add Configuration Helpers
|
|
- [x] Create `SmartProxyConfig.fromSimple()` helper for basic setups (part of validation)
|
|
- [x] Add validation for common misconfigurations
|
|
- [x] Provide warning messages for deprecated patterns
|
|
- [x] Include auto-correction suggestions
|
|
|
|
## Implementation Steps
|
|
|
|
### Phase 1: Configuration Support ✅
|
|
1. ✅ Update ISmartProxyOptions interface to clarify ACME placement
|
|
2. ✅ Modify SmartProxy constructor to handle top-level ACME config
|
|
3. ✅ Update SmartCertManager to accept global ACME defaults
|
|
4. ✅ Add configuration validation and helpful error messages
|
|
|
|
### Phase 2: Testing ✅
|
|
1. ✅ Add tests for both configuration styles
|
|
2. ✅ Test ACME initialization with various configurations
|
|
3. ✅ Verify certificate acquisition works in all scenarios
|
|
4. ✅ Test error handling and messaging
|
|
|
|
### Phase 3: Documentation ✅
|
|
1. ✅ Update main README with clear ACME examples
|
|
2. ✅ Create dedicated certificate-management.md guide
|
|
3. ✅ Add migration guide for v18 to v19 users
|
|
4. ✅ Include troubleshooting section
|
|
|
|
## Example Simplified Configuration
|
|
|
|
```typescript
|
|
// Simplified configuration with top-level ACME
|
|
const proxy = new SmartProxy({
|
|
// Global ACME settings (applies to all routes with certificate: 'auto')
|
|
acme: {
|
|
email: 'ssl@example.com',
|
|
useProduction: false,
|
|
port: 80 // Automatically listened on when needed
|
|
},
|
|
|
|
routes: [
|
|
{
|
|
name: 'secure-site',
|
|
match: { domains: 'example.com', ports: 443 },
|
|
action: {
|
|
type: 'forward',
|
|
target: { host: 'localhost', port: 8080 },
|
|
tls: {
|
|
mode: 'terminate',
|
|
certificate: 'auto' // Uses global ACME settings
|
|
}
|
|
}
|
|
}
|
|
]
|
|
});
|
|
|
|
// Or with route-specific ACME override
|
|
const proxy = new SmartProxy({
|
|
routes: [
|
|
{
|
|
name: 'special-site',
|
|
match: { domains: 'special.com', ports: 443 },
|
|
action: {
|
|
type: 'forward',
|
|
target: { host: 'localhost', port: 8080 },
|
|
tls: {
|
|
mode: 'terminate',
|
|
certificate: 'auto',
|
|
acme: { // Route-specific override
|
|
email: 'special@example.com',
|
|
useProduction: true
|
|
}
|
|
}
|
|
}
|
|
}
|
|
]
|
|
});
|
|
```
|
|
|
|
## Success Criteria ✅
|
|
1. ✅ Users can configure ACME at top-level for all routes
|
|
2. ✅ Clear error messages guide users to correct configuration
|
|
3. ✅ Certificate acquisition works with minimal configuration
|
|
4. ✅ Documentation clearly explains all configuration options
|
|
5. ✅ Migration from v18 to v19 is straightforward
|
|
|
|
## Timeline
|
|
- Phase 1: 2-3 days
|
|
- Phase 2: 1-2 days
|
|
- Phase 3: 1 day
|
|
|
|
Total estimated time: 5-6 days
|
|
|
|
## Notes
|
|
- Maintain backward compatibility with existing route-level ACME config
|
|
- Consider adding a configuration wizard for interactive setup
|
|
- Explore integration with popular DNS providers for DNS-01 challenges
|
|
- Add metrics/monitoring for certificate renewal status |