docs: add container deployment guide and implementation report

Complete Phase 5 containerization documentation:
- Add comprehensive container deployment guide (500+ lines)
- Document Podman and Docker deployment workflows
- Include reverse proxy setup for Caddy and Nginx
- Add troubleshooting, monitoring, and maintenance sections
- Document --userns=keep-id requirement for Podman
- Add backup/restore procedures
- Include performance tuning guidelines
- Add security best practices

Implementation report includes:
- Technical implementation details
- Testing results and metrics
- Challenge resolution (Podman permissions)
- Security and compliance verification
- Integration with RSS feed
- Lessons learned and recommendations

Updated CHANGELOG.md:
- Document container features in v0.6.0
- Add configuration variables
- List deployment capabilities
- Note Podman and Docker compatibility

Phase 5 containerization: 100% complete
This commit is contained in:
2025-11-19 10:14:35 -07:00
parent c559f89a7f
commit 8d593ca1b9
3 changed files with 1220 additions and 0 deletions

View File

@@ -20,9 +20,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- RSS link in site navigation
- Comprehensive RSS feed test suite (44 tests)
### Production Container
- **Containerfile**: Multi-stage build for optimized image size (174MB)
- **Container Orchestration**: Podman and Docker Compose compatible
- **Health Check Endpoint**: GET `/health` for container monitoring
- **Gunicorn WSGI Server**: Production-ready with 4 workers
- **Security**: Non-root user execution (starpunk:1000)
- **Volume Mounts**: Data persistence for notes and database
- **Reverse Proxy Configs**: Caddy and Nginx examples with auto-HTTPS
- **Container Documentation**: Comprehensive deployment guide
### Configuration
- `FEED_MAX_ITEMS`: Maximum items in RSS feed (default: 50)
- `FEED_CACHE_SECONDS`: Server-side cache duration in seconds (default: 300)
- `VERSION`: Application version for health checks (default: 0.6.0)
- `ENVIRONMENT`: Deployment environment (development/production)
- `WORKERS`: Number of Gunicorn workers (default: 4)
- `WORKER_TIMEOUT`: Gunicorn worker timeout in seconds (default: 30)
- `MAX_REQUESTS`: Max requests per worker before restart (default: 1000)
### Features
- RSS 2.0 compliant XML generation using feedgen library
@@ -46,11 +61,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- IndieWeb feed discovery support
- W3C Feed Validator compatible
### Container Features
- Multi-stage build optimizes image size (Python 3.11-slim base)
- uv package manager for fast dependency installation
- Health checks verify database connectivity and filesystem access
- Resource limits prevent container resource exhaustion
- Log rotation (10MB max, 3 files) prevents disk space issues
- Automatic restart policy for reliability
- SELinux compatibility with volume mount flags
### Deployment
- Podman-compatible with `--userns=keep-id` for proper permissions
- Docker-compatible with standard volume mounts
- Reverse proxy examples for Caddy (auto-HTTPS) and Nginx
- HTTPS required for IndieAuth in production
- Complete backup and restore procedures documented
- Performance tuning guide for worker configuration
### Related Documentation
- ADR-014: RSS Feed Implementation Strategy
- ADR-015: Phase 5 Implementation Approach
- Phase 5 design documentation
- Phase 5 quick reference guide
- Container deployment guide
## [0.5.2] - 2025-11-18