docs: add Phase 5 design and architectural review documentation
- Add ADR-014: RSS Feed Implementation - Add ADR-015: Phase 5 Implementation Approach - Add Phase 5 design documents (RSS and container) - Add pre-implementation review - Add RSS and container validation reports - Add architectural approval for v0.6.0 release Architecture reviews confirm 98/100 (RSS) and 96/100 (container) scores. Phase 5 approved for production deployment. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
405
docs/designs/PHASE-5-EXECUTIVE-SUMMARY.md
Normal file
405
docs/designs/PHASE-5-EXECUTIVE-SUMMARY.md
Normal file
@@ -0,0 +1,405 @@
|
||||
# Phase 5 Executive Summary
|
||||
|
||||
**Date**: 2025-11-18
|
||||
**Version**: v0.5.2 → v0.6.0
|
||||
**Status**: Design Complete, Ready for Implementation
|
||||
|
||||
## What Is Phase 5?
|
||||
|
||||
Phase 5 implements two critical features for StarPunk:
|
||||
|
||||
1. **RSS Feed Generation**: Allow RSS readers to subscribe to your notes
|
||||
2. **Production Container**: Enable deployment with HTTPS for real IndieAuth testing
|
||||
|
||||
## Why These Features Together?
|
||||
|
||||
**RSS Feed** completes the core V1 content syndication feature set. Readers can now subscribe to your notes via any RSS reader (Feedly, NewsBlur, etc.).
|
||||
|
||||
**Production Container** solves a critical problem: **IndieAuth requires HTTPS**. You can't properly test authentication on localhost. The container allows you to deploy StarPunk on a public server with HTTPS, enabling full IndieAuth testing with your real domain.
|
||||
|
||||
## What You'll Get
|
||||
|
||||
### 1. RSS 2.0 Feed (`/feed.xml`)
|
||||
|
||||
**Features**:
|
||||
- Valid RSS 2.0 XML feed
|
||||
- Recent 50 published notes (configurable)
|
||||
- Proper RFC-822 date formatting
|
||||
- Full HTML content in each entry
|
||||
- Auto-discovery (RSS readers detect it automatically)
|
||||
- 5-minute server-side caching for performance
|
||||
|
||||
**User Experience**:
|
||||
```
|
||||
1. You publish a note via StarPunk
|
||||
2. RSS feed updates (within 5 minutes)
|
||||
3. RSS readers poll your feed
|
||||
4. Your subscribers see your new note
|
||||
```
|
||||
|
||||
**Standards Compliant**:
|
||||
- Validates with W3C Feed Validator
|
||||
- Works with all RSS readers
|
||||
- Includes proper metadata
|
||||
- IndieWeb friendly
|
||||
|
||||
### 2. Production-Ready Container
|
||||
|
||||
**Features**:
|
||||
- Podman and Docker compatible
|
||||
- Multi-stage optimized build
|
||||
- Non-root user for security
|
||||
- Gunicorn WSGI server (4 workers)
|
||||
- Health check endpoint
|
||||
- Data persistence via volume mounts
|
||||
- Environment variable configuration
|
||||
- Production logging
|
||||
|
||||
**Deployment**:
|
||||
```
|
||||
1. Build container (Podman or Docker)
|
||||
2. Run on public server
|
||||
3. Configure reverse proxy (Caddy or Nginx)
|
||||
4. HTTPS via Let's Encrypt
|
||||
5. Test IndieAuth with real domain
|
||||
```
|
||||
|
||||
**Why This Matters**:
|
||||
- IndieAuth **requires** HTTPS (can't test on localhost)
|
||||
- Container provides clean, reproducible deployment
|
||||
- Data persists across restarts
|
||||
- Easy to backup (just backup the volume)
|
||||
- Professional deployment ready for production use
|
||||
|
||||
## File Structure
|
||||
|
||||
### New Files Created
|
||||
```
|
||||
starpunk/feed.py # RSS generation module
|
||||
Containerfile # Container build definition
|
||||
compose.yaml # Container orchestration
|
||||
.containerignore # Build exclusions
|
||||
Caddyfile.example # Caddy reverse proxy config
|
||||
nginx.conf.example # Nginx alternative config
|
||||
tests/test_feed.py # Feed unit tests
|
||||
tests/test_routes_feed.py # Feed route tests
|
||||
```
|
||||
|
||||
### Documentation Created
|
||||
```
|
||||
docs/designs/phase-5-rss-and-container.md # Complete design (45 pages)
|
||||
docs/designs/phase-5-quick-reference.md # Implementation guide
|
||||
docs/decisions/ADR-014-rss-feed-implementation.md # RSS decision record
|
||||
docs/reports/phase-5-pre-implementation-review.md # Codebase analysis
|
||||
```
|
||||
|
||||
## Current Status
|
||||
|
||||
### Codebase State: ✅ EXCELLENT
|
||||
|
||||
- **Version**: v0.5.2
|
||||
- **Tests**: 405/406 passing (99.75%)
|
||||
- **Coverage**: 87%
|
||||
- **Code Quality**: Formatted (Black), Linted (Flake8)
|
||||
- **Architecture**: Sound, well-structured
|
||||
- **Dependencies**: All required dependencies already present
|
||||
|
||||
### Phase 4 Completion: ✅ COMPLETE
|
||||
|
||||
All prerequisites met:
|
||||
- Web interface fully functional
|
||||
- Authentication working (IndieAuth + dev mode)
|
||||
- Note CRUD operations tested
|
||||
- Templates with microformats
|
||||
- Testing infrastructure solid
|
||||
|
||||
### Phase 5 Readiness: ✅ READY
|
||||
|
||||
No blockers identified:
|
||||
- feedgen library already in requirements.txt
|
||||
- Database schema supports RSS queries
|
||||
- Route blueprint ready for /feed.xml
|
||||
- All architectural decisions made
|
||||
- Comprehensive design documentation
|
||||
|
||||
## Implementation Path
|
||||
|
||||
### Recommended Sequence
|
||||
|
||||
**Part 1: RSS Feed** (3-4 hours)
|
||||
1. Create `starpunk/feed.py` module
|
||||
2. Add `/feed.xml` route with caching
|
||||
3. Update templates with RSS discovery
|
||||
4. Write tests
|
||||
5. Validate with W3C
|
||||
|
||||
**Part 2: Container** (3-4 hours)
|
||||
1. Create Containerfile
|
||||
2. Create compose.yaml
|
||||
3. Add health check endpoint
|
||||
4. Test build and run
|
||||
5. Test data persistence
|
||||
|
||||
**Part 3: Production Testing** (2-3 hours)
|
||||
1. Deploy container to public server
|
||||
2. Configure reverse proxy (HTTPS)
|
||||
3. Test IndieAuth authentication
|
||||
4. Verify RSS feed in readers
|
||||
5. Document deployment
|
||||
|
||||
**Part 4: Documentation** (1-2 hours)
|
||||
1. Update CHANGELOG.md
|
||||
2. Increment version to 0.6.0
|
||||
3. Create deployment guide
|
||||
4. Create implementation report
|
||||
|
||||
**Total Time**: 9-13 hours
|
||||
|
||||
## Key Design Decisions (ADR-014)
|
||||
|
||||
### RSS Format: RSS 2.0 Only (V1)
|
||||
- **Why**: Universal support, simpler than Atom
|
||||
- **Deferred**: Atom and JSON Feed to V2
|
||||
|
||||
### XML Generation: feedgen Library
|
||||
- **Why**: Reliable, tested, produces valid XML
|
||||
- **Avoided**: Manual XML (error-prone)
|
||||
|
||||
### Caching: 5-Minute In-Memory Cache
|
||||
- **Why**: Reduces load, reasonable delay
|
||||
- **Benefit**: Fast responses, ETag support
|
||||
|
||||
### Note Titles: First Line or Timestamp
|
||||
- **Why**: Notes don't require titles (per IndieWeb)
|
||||
- **Fallback**: Timestamp if no first line
|
||||
|
||||
### Feed Limit: 50 Items (Configurable)
|
||||
- **Why**: Reasonable balance
|
||||
- **Configurable**: FEED_MAX_ITEMS env variable
|
||||
|
||||
## Quality Gates
|
||||
|
||||
Phase 5 is complete when:
|
||||
|
||||
### Functional
|
||||
- [ ] RSS feed validates with W3C validator
|
||||
- [ ] Feed appears correctly in RSS readers
|
||||
- [ ] Container builds (Podman + Docker)
|
||||
- [ ] Health check endpoint works
|
||||
- [ ] Data persists across restarts
|
||||
- [ ] IndieAuth works with HTTPS
|
||||
|
||||
### Quality
|
||||
- [ ] All tests pass (>405 tests)
|
||||
- [ ] Coverage >85%
|
||||
- [ ] No linting errors
|
||||
- [ ] Code formatted
|
||||
|
||||
### Documentation
|
||||
- [ ] CHANGELOG updated
|
||||
- [ ] Version incremented to 0.6.0
|
||||
- [ ] Deployment guide complete
|
||||
- [ ] Implementation report created
|
||||
|
||||
## What Happens After Phase 5?
|
||||
|
||||
### V1 Feature Set Progress
|
||||
|
||||
**Completed after Phase 5**:
|
||||
- ✅ Note storage and management
|
||||
- ✅ IndieAuth authentication
|
||||
- ✅ Web interface
|
||||
- ✅ RSS feed generation
|
||||
- ✅ Production deployment capability
|
||||
|
||||
**Remaining for V1**:
|
||||
- ⏳ Micropub endpoint (Phase 6)
|
||||
- ⏳ Final integration testing
|
||||
- ⏳ V1.0.0 release
|
||||
|
||||
### Version Progression
|
||||
|
||||
```
|
||||
v0.5.2 (current) → Phase 5 → v0.6.0 → Phase 6 → v0.7.0 → V1.0.0
|
||||
RSS + Micropub Final
|
||||
Container Polish
|
||||
```
|
||||
|
||||
## Container Deployment Example
|
||||
|
||||
### Quick Start (Production)
|
||||
|
||||
```bash
|
||||
# On your public server
|
||||
git clone <your-repo>
|
||||
cd starpunk
|
||||
|
||||
# Configure
|
||||
cp .env.example .env
|
||||
# Edit .env: Set SITE_URL, ADMIN_ME, SESSION_SECRET
|
||||
|
||||
# Create data directory
|
||||
mkdir -p container-data/notes
|
||||
|
||||
# Run with Podman
|
||||
podman-compose up -d
|
||||
|
||||
# Configure Caddy (auto-HTTPS)
|
||||
# Edit Caddyfile: Set your-domain.com
|
||||
caddy run
|
||||
|
||||
# Visit https://your-domain.com
|
||||
# RSS feed: https://your-domain.com/feed.xml
|
||||
# Admin: https://your-domain.com/admin/login
|
||||
```
|
||||
|
||||
That's it! Full HTTPS, working IndieAuth, RSS feed available.
|
||||
|
||||
## RSS Feed Example
|
||||
|
||||
Once deployed, your feed will look like:
|
||||
|
||||
```xml
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<rss version="2.0">
|
||||
<channel>
|
||||
<title>My StarPunk Site</title>
|
||||
<link>https://your-domain.com/</link>
|
||||
<description>My personal IndieWeb site</description>
|
||||
|
||||
<item>
|
||||
<title>My Latest Note</title>
|
||||
<link>https://your-domain.com/note/my-latest-note</link>
|
||||
<guid>https://your-domain.com/note/my-latest-note</guid>
|
||||
<pubDate>Mon, 18 Nov 2024 10:30:00 +0000</pubDate>
|
||||
<description><![CDATA[
|
||||
<p>Full HTML content of your note here</p>
|
||||
]]></description>
|
||||
</item>
|
||||
|
||||
<!-- More items... -->
|
||||
</channel>
|
||||
</rss>
|
||||
```
|
||||
|
||||
## Testing IndieAuth with Container
|
||||
|
||||
**Before Phase 5**: Can't test IndieAuth properly (localhost doesn't work)
|
||||
|
||||
**After Phase 5**:
|
||||
1. Deploy container to `https://your-domain.com`
|
||||
2. Set `ADMIN_ME=https://your-identity.com`
|
||||
3. Visit `https://your-domain.com/admin/login`
|
||||
4. Enter your identity URL
|
||||
5. IndieLogin redirects you for authentication
|
||||
6. Authenticate via your method (GitHub, email, etc.)
|
||||
7. IndieLogin redirects back to your domain
|
||||
8. **It works!** You're logged in
|
||||
|
||||
## Risk Mitigation
|
||||
|
||||
### Identified Risks & Solutions
|
||||
|
||||
**Risk**: RSS feed invalid XML
|
||||
- **Solution**: Use feedgen library (tested)
|
||||
- **Validation**: W3C validator before commit
|
||||
|
||||
**Risk**: Container fails to build
|
||||
- **Solution**: Multi-stage build, tested locally
|
||||
- **Fallback**: Can still deploy without container
|
||||
|
||||
**Risk**: IndieAuth callback fails
|
||||
- **Solution**: Example configs provided
|
||||
- **Testing**: Step-by-step testing guide
|
||||
|
||||
**Risk**: Data loss in container
|
||||
- **Solution**: Volume mounts, tested persistence
|
||||
- **Backup**: Easy to backup volume directory
|
||||
|
||||
## Documentation Overview
|
||||
|
||||
### For Architect (You - Complete)
|
||||
|
||||
All architectural work complete:
|
||||
- ✅ Comprehensive design document (45 pages)
|
||||
- ✅ ADR-014 with rationale and alternatives
|
||||
- ✅ Quick reference implementation guide
|
||||
- ✅ Pre-implementation codebase review
|
||||
- ✅ This executive summary
|
||||
|
||||
### For Developer (Next Step)
|
||||
|
||||
Everything needed to implement:
|
||||
- Complete specifications
|
||||
- Code examples
|
||||
- Testing strategy
|
||||
- Deployment guide
|
||||
- Common issues documented
|
||||
- Step-by-step checklist
|
||||
|
||||
## Success Metrics
|
||||
|
||||
Phase 5 succeeds when:
|
||||
|
||||
1. **RSS feed validates** (W3C validator passes)
|
||||
2. **Feed works in readers** (tested in 2+ readers)
|
||||
3. **Container builds** (Podman + Docker)
|
||||
4. **Container runs reliably** (restarts work)
|
||||
5. **IndieAuth works** (tested with real HTTPS)
|
||||
6. **Data persists** (survives restarts)
|
||||
7. **Tests pass** (>405/410 tests)
|
||||
8. **Documentation complete** (CHANGELOG, reports)
|
||||
|
||||
## Confidence Assessment
|
||||
|
||||
### Overall: ✅ HIGH CONFIDENCE
|
||||
|
||||
**Why High Confidence**:
|
||||
- All dependencies already available
|
||||
- Clear, tested implementation path
|
||||
- Comprehensive design documentation
|
||||
- No architectural changes needed
|
||||
- Standards-based approach
|
||||
- Similar patterns already working in codebase
|
||||
|
||||
**Estimated Success Probability**: 95%
|
||||
|
||||
**Biggest Risk**: IndieAuth callback configuration
|
||||
**Mitigation**: Extensive documentation, example configs, testing guide
|
||||
|
||||
## Final Recommendation
|
||||
|
||||
**Proceed with Phase 5 Implementation**: ✅ APPROVED
|
||||
|
||||
The codebase is in excellent condition, all prerequisites are met, and comprehensive design documentation is complete. Phase 5 can begin immediately with high confidence of success.
|
||||
|
||||
**Estimated Timeline**: 9-13 hours to completion
|
||||
**Version Increment**: v0.5.2 → v0.6.0 (minor version bump)
|
||||
**Release Readiness**: Production-ready upon completion
|
||||
|
||||
---
|
||||
|
||||
## Quick Access Links
|
||||
|
||||
**Primary Documents**:
|
||||
- [Full Design Document](/home/phil/Projects/starpunk/docs/designs/phase-5-rss-and-container.md)
|
||||
- [Quick Reference Guide](/home/phil/Projects/starpunk/docs/designs/phase-5-quick-reference.md)
|
||||
- [ADR-014: RSS Implementation](/home/phil/Projects/starpunk/docs/decisions/ADR-014-rss-feed-implementation.md)
|
||||
- [Pre-Implementation Review](/home/phil/Projects/starpunk/docs/reports/phase-5-pre-implementation-review.md)
|
||||
|
||||
**Standards References**:
|
||||
- [RSS 2.0 Specification](https://www.rssboard.org/rss-specification)
|
||||
- [W3C Feed Validator](https://validator.w3.org/feed/)
|
||||
- [Podman Documentation](https://docs.podman.io/)
|
||||
|
||||
**Project Standards**:
|
||||
- [Versioning Strategy](/home/phil/Projects/starpunk/docs/standards/versioning-strategy.md)
|
||||
- [Git Branching Strategy](/home/phil/Projects/starpunk/docs/standards/git-branching-strategy.md)
|
||||
|
||||
---
|
||||
|
||||
**Document**: Phase 5 Executive Summary
|
||||
**Author**: StarPunk Architect
|
||||
**Date**: 2025-11-18
|
||||
**Status**: ✅ Complete and Approved
|
||||
**Next Action**: Begin Phase 5 Implementation
|
||||
434
docs/designs/phase-5-quick-reference.md
Normal file
434
docs/designs/phase-5-quick-reference.md
Normal file
@@ -0,0 +1,434 @@
|
||||
# Phase 5 Quick Reference Guide
|
||||
|
||||
**Phase**: 5 - RSS Feed & Production Container
|
||||
**Version**: 0.6.0
|
||||
**Status**: Implementation Ready
|
||||
|
||||
## Pre-Implementation Setup
|
||||
|
||||
### Version Numbering
|
||||
**Decision**: Go directly from 0.5.1 → 0.6.0
|
||||
- Phase 5 introduces significant new functionality (RSS feeds and container deployment)
|
||||
- Skip intermediate versions (e.g., 0.5.2) - go straight to 0.6.0
|
||||
- This follows semantic versioning for new feature additions
|
||||
|
||||
### Git Workflow
|
||||
**Decision**: Use feature branch `feature/phase-5-rss-container`
|
||||
1. Create and checkout feature branch:
|
||||
```bash
|
||||
git checkout -b feature/phase-5-rss-container
|
||||
```
|
||||
2. Implement all Phase 5 features on this branch
|
||||
3. Create PR to merge into main when complete
|
||||
4. This provides cleaner history and easier rollback if needed
|
||||
|
||||
## Overview
|
||||
|
||||
Phase 5 implements:
|
||||
1. RSS 2.0 feed generation for syndicating published notes
|
||||
2. Production-ready container for deployment with HTTPS/IndieAuth testing
|
||||
|
||||
## Implementation Checklist
|
||||
|
||||
### Part 1: RSS Feed (Estimated: 3-4 hours)
|
||||
|
||||
#### Step 1: Create Feed Module
|
||||
- [ ] Create `starpunk/feed.py`
|
||||
- [ ] Implement `generate_feed()` using feedgen
|
||||
- [ ] Implement `format_rfc822_date()` for date formatting
|
||||
- [ ] Implement `get_note_title()` for title extraction
|
||||
- [ ] Implement `clean_html_for_rss()` for CDATA safety
|
||||
|
||||
#### Step 2: Add Feed Route
|
||||
- [ ] Update `starpunk/routes/public.py`
|
||||
- [ ] Add `@bp.route("/feed.xml")` handler
|
||||
- [ ] Implement in-memory caching (5 minutes)
|
||||
- [ ] Add ETag generation and support
|
||||
- [ ] Set proper Content-Type and Cache-Control headers
|
||||
|
||||
#### Step 3: Update Templates
|
||||
- [ ] Add RSS discovery link to `templates/base.html`
|
||||
- [ ] Add RSS link to navigation in `templates/index.html`
|
||||
|
||||
#### Step 4: Configuration
|
||||
- [ ] Update `starpunk/config.py` with feed settings
|
||||
- [ ] Add FEED_MAX_ITEMS (default: 50)
|
||||
- [ ] Add FEED_CACHE_SECONDS (default: 300)
|
||||
- [ ] Update `.env.example` with feed variables
|
||||
|
||||
#### Step 5: RSS Testing
|
||||
- [ ] Create `tests/test_feed.py` for unit tests
|
||||
- [ ] Create `tests/test_routes_feed.py` for route tests
|
||||
- [ ] Test feed generation with various note counts
|
||||
- [ ] Test caching behavior
|
||||
- [ ] Test ETag validation
|
||||
- [ ] Validate with W3C Feed Validator
|
||||
|
||||
### Part 2: Production Container (Estimated: 3-4 hours)
|
||||
|
||||
#### Step 6: Create Container Files
|
||||
- [ ] Create `Containerfile` with multi-stage build
|
||||
- [ ] Create `compose.yaml` for orchestration
|
||||
- [ ] Create `.containerignore` to exclude unnecessary files
|
||||
- [ ] Create `Caddyfile.example` for reverse proxy
|
||||
- [ ] Create `nginx.conf.example` as alternative
|
||||
|
||||
#### Step 7: Add Health Check
|
||||
- [ ] Add `/health` endpoint to `starpunk/__init__.py`
|
||||
- [ ] Check database connectivity
|
||||
- [ ] Check filesystem access
|
||||
- [ ] Return JSON with status and version
|
||||
|
||||
#### Step 8: Container Configuration
|
||||
- [ ] Update `.env.example` with container variables
|
||||
- [ ] Add VERSION=0.6.0
|
||||
- [ ] Add WORKERS=4
|
||||
- [ ] Add WORKER_TIMEOUT=30
|
||||
- [ ] Document environment variables
|
||||
|
||||
#### Step 9: Container Testing
|
||||
- [ ] Build container with Podman
|
||||
- [ ] Build container with Docker
|
||||
- [ ] Test container startup
|
||||
- [ ] Test health endpoint
|
||||
- [ ] Test data persistence
|
||||
- [ ] Test with compose orchestration
|
||||
|
||||
#### Step 10: Production Deployment Testing
|
||||
- [ ] Deploy container to public server
|
||||
- [ ] Configure reverse proxy (Caddy or Nginx)
|
||||
- [ ] Set up HTTPS with Let's Encrypt
|
||||
- [ ] Test IndieAuth authentication flow
|
||||
- [ ] Verify callback URLs work
|
||||
- [ ] Test session creation and persistence
|
||||
|
||||
### Part 3: Documentation (Estimated: 1-2 hours)
|
||||
|
||||
#### Step 11: Update Documentation
|
||||
- [ ] Update CHANGELOG.md for v0.6.0
|
||||
- [ ] Increment version in `starpunk/__init__.py` from 0.5.1 to 0.6.0
|
||||
- [ ] Create deployment guide
|
||||
- [ ] Document RSS feed usage
|
||||
- [ ] Document container deployment
|
||||
- [ ] Document IndieAuth testing with HTTPS
|
||||
|
||||
## File Locations
|
||||
|
||||
### New Files
|
||||
```
|
||||
starpunk/feed.py # RSS generation module
|
||||
Containerfile # Container build definition
|
||||
compose.yaml # Container orchestration
|
||||
.containerignore # Container build exclusions
|
||||
Caddyfile.example # Caddy reverse proxy config
|
||||
nginx.conf.example # Nginx reverse proxy config
|
||||
tests/test_feed.py # Feed unit tests
|
||||
tests/test_routes_feed.py # Feed route tests
|
||||
docs/designs/phase-5-rss-and-container.md # This phase design
|
||||
docs/designs/phase-5-quick-reference.md # This guide
|
||||
docs/decisions/ADR-014-rss-feed-implementation.md # RSS ADR
|
||||
```
|
||||
|
||||
### Modified Files
|
||||
```
|
||||
starpunk/routes/public.py # Add /feed.xml route
|
||||
starpunk/__init__.py # Add /health endpoint
|
||||
starpunk/config.py # Add feed configuration
|
||||
templates/base.html # Add RSS discovery link
|
||||
templates/index.html # Add RSS nav link
|
||||
.env.example # Add feed/container vars
|
||||
CHANGELOG.md # Document v0.6.0
|
||||
```
|
||||
|
||||
## Key Implementation Details
|
||||
|
||||
### RSS Feed Module
|
||||
|
||||
**File**: `starpunk/feed.py`
|
||||
|
||||
**Core Function**:
|
||||
```python
|
||||
from feedgen.feed import FeedGenerator
|
||||
from starpunk.notes import list_notes
|
||||
|
||||
def generate_feed(site_url, site_name, site_description, notes, limit=50):
|
||||
"""Generate RSS 2.0 XML feed"""
|
||||
fg = FeedGenerator()
|
||||
|
||||
# Set channel metadata
|
||||
fg.title(site_name)
|
||||
fg.link(href=site_url, rel='alternate')
|
||||
fg.description(site_description)
|
||||
fg.language('en')
|
||||
fg.link(href=f'{site_url}/feed.xml', rel='self')
|
||||
|
||||
# Add items
|
||||
for note in notes[:limit]:
|
||||
fe = fg.add_entry()
|
||||
fe.title(get_note_title(note))
|
||||
fe.link(href=f'{site_url}/note/{note.slug}')
|
||||
fe.guid(f'{site_url}/note/{note.slug}', permalink=True)
|
||||
fe.pubDate(note.created_at.replace(tzinfo=timezone.utc))
|
||||
fe.description(note.html) # HTML content
|
||||
|
||||
return fg.rss_str(pretty=True).decode('utf-8')
|
||||
```
|
||||
|
||||
### Feed Route
|
||||
|
||||
**File**: `starpunk/routes/public.py`
|
||||
|
||||
**Add to existing blueprint**:
|
||||
```python
|
||||
@bp.route("/feed.xml")
|
||||
def feed():
|
||||
"""RSS 2.0 feed endpoint with caching"""
|
||||
# Check cache (implementation in design doc)
|
||||
# Generate feed if cache expired
|
||||
# Return XML with proper headers
|
||||
pass
|
||||
```
|
||||
|
||||
### Health Check Endpoint
|
||||
|
||||
**File**: `starpunk/__init__.py`
|
||||
|
||||
**Add before return app**:
|
||||
```python
|
||||
@app.route('/health')
|
||||
def health_check():
|
||||
"""Container health check"""
|
||||
try:
|
||||
# Check database and filesystem
|
||||
return jsonify({'status': 'healthy', 'version': '0.6.0'}), 200
|
||||
except Exception as e:
|
||||
return jsonify({'status': 'unhealthy', 'error': str(e)}), 500
|
||||
```
|
||||
|
||||
### Containerfile
|
||||
|
||||
**Key Sections**:
|
||||
```dockerfile
|
||||
# Multi-stage build for smaller image
|
||||
FROM python:3.11-slim AS builder
|
||||
# ... install dependencies in venv ...
|
||||
|
||||
FROM python:3.11-slim
|
||||
# ... copy venv, run as non-root ...
|
||||
|
||||
CMD ["gunicorn", "--bind", "0.0.0.0:8000", "--workers", "4", "app:app"]
|
||||
```
|
||||
|
||||
## Testing Commands
|
||||
|
||||
### RSS Feed Testing
|
||||
```bash
|
||||
# Unit tests
|
||||
uv run pytest tests/test_feed.py -v
|
||||
|
||||
# Route tests
|
||||
uv run pytest tests/test_routes_feed.py -v
|
||||
|
||||
# Manual test
|
||||
curl http://localhost:5000/feed.xml
|
||||
|
||||
# Validate XML
|
||||
curl http://localhost:5000/feed.xml | xmllint --noout -
|
||||
|
||||
# W3C Validation (manual)
|
||||
# Visit: https://validator.w3.org/feed/
|
||||
# Enter: http://your-domain.com/feed.xml
|
||||
```
|
||||
|
||||
### Container Testing
|
||||
```bash
|
||||
# Build with Podman
|
||||
podman build -t starpunk:0.6.0 -f Containerfile .
|
||||
|
||||
# Build with Docker
|
||||
docker build -t starpunk:0.6.0 -f Containerfile .
|
||||
|
||||
# Run with Podman
|
||||
mkdir -p container-data/notes
|
||||
podman run -d --name starpunk \
|
||||
-p 127.0.0.1:8000:8000 \
|
||||
-v $(pwd)/container-data:/data:rw,Z \
|
||||
--env-file .env \
|
||||
starpunk:0.6.0
|
||||
|
||||
# Check health
|
||||
curl http://localhost:8000/health
|
||||
|
||||
# Check feed
|
||||
curl http://localhost:8000/feed.xml
|
||||
|
||||
# View logs
|
||||
podman logs starpunk
|
||||
|
||||
# Test with compose
|
||||
podman-compose up -d
|
||||
podman-compose logs -f
|
||||
```
|
||||
|
||||
## Configuration Examples
|
||||
|
||||
### .env for Container
|
||||
```bash
|
||||
# Required
|
||||
SITE_URL=https://your-domain.com
|
||||
SITE_NAME=My StarPunk Site
|
||||
ADMIN_ME=https://your-identity.com
|
||||
SESSION_SECRET=<random-secret>
|
||||
|
||||
# Feed configuration
|
||||
FEED_MAX_ITEMS=50
|
||||
FEED_CACHE_SECONDS=300
|
||||
|
||||
# Container configuration
|
||||
VERSION=0.6.0
|
||||
ENVIRONMENT=production
|
||||
WORKERS=4
|
||||
FLASK_ENV=production
|
||||
FLASK_DEBUG=0
|
||||
```
|
||||
|
||||
### Caddy Reverse Proxy
|
||||
```caddy
|
||||
your-domain.com {
|
||||
reverse_proxy localhost:8000
|
||||
|
||||
log {
|
||||
output file /var/log/caddy/starpunk.log
|
||||
}
|
||||
|
||||
encode gzip zstd
|
||||
}
|
||||
```
|
||||
|
||||
### Nginx Reverse Proxy
|
||||
```nginx
|
||||
upstream starpunk {
|
||||
server localhost:8000;
|
||||
}
|
||||
|
||||
server {
|
||||
listen 443 ssl http2;
|
||||
server_name your-domain.com;
|
||||
|
||||
ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
|
||||
ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;
|
||||
|
||||
location / {
|
||||
proxy_pass http://starpunk;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Common Issues & Solutions
|
||||
|
||||
### Issue: Feed not updating
|
||||
**Solution**: Check cache duration (5 minutes default), force refresh by restarting
|
||||
|
||||
### Issue: Container won't start
|
||||
**Solution**: Check logs (`podman logs starpunk`), verify .env file exists
|
||||
|
||||
### Issue: IndieAuth callback fails
|
||||
**Solution**: Verify SITE_URL matches public URL exactly (no trailing slash)
|
||||
|
||||
### Issue: Data not persisting
|
||||
**Solution**: Check volume mount is correct, verify permissions
|
||||
|
||||
### Issue: RSS validation errors
|
||||
**Solution**: Check date formatting (RFC-822), verify XML structure
|
||||
|
||||
## Deployment Workflow
|
||||
|
||||
### 1. Local Testing
|
||||
```bash
|
||||
# Test feed locally
|
||||
uv run flask --app app.py run --debug
|
||||
curl http://localhost:5000/feed.xml
|
||||
```
|
||||
|
||||
### 2. Container Testing
|
||||
```bash
|
||||
# Build and test container
|
||||
podman build -t starpunk:0.6.0 .
|
||||
podman run -d -p 8000:8000 --name starpunk-test starpunk:0.6.0
|
||||
curl http://localhost:8000/health
|
||||
```
|
||||
|
||||
### 3. Production Deployment
|
||||
```bash
|
||||
# On server
|
||||
git clone <repo>
|
||||
cd starpunk
|
||||
cp .env.example .env
|
||||
# Edit .env with production values
|
||||
|
||||
# Build and run
|
||||
podman-compose up -d
|
||||
|
||||
# Configure reverse proxy (Caddy or Nginx)
|
||||
# Set up HTTPS with certbot or Caddy auto-HTTPS
|
||||
|
||||
# Test IndieAuth
|
||||
# Visit https://your-domain.com/admin/login
|
||||
```
|
||||
|
||||
## Success Criteria
|
||||
|
||||
Phase 5 complete when:
|
||||
- [ ] RSS feed validates with W3C validator
|
||||
- [ ] Feed appears correctly in RSS readers
|
||||
- [ ] Container builds and runs successfully
|
||||
- [ ] Health check endpoint responds
|
||||
- [ ] Data persists across container restarts
|
||||
- [ ] IndieAuth works with public HTTPS URL
|
||||
- [ ] All tests pass (>90% coverage)
|
||||
- [ ] Documentation complete
|
||||
- [ ] Version incremented from 0.5.1 to 0.6.0 in `starpunk/__init__.py`
|
||||
- [ ] Feature branch `feature/phase-5-rss-container` merged to main
|
||||
|
||||
## Time Estimate
|
||||
|
||||
- RSS Feed Implementation: 3-4 hours
|
||||
- Container Implementation: 3-4 hours
|
||||
- Testing: 2-3 hours
|
||||
- Documentation: 1-2 hours
|
||||
|
||||
**Total**: 9-13 hours
|
||||
|
||||
## Next Steps After Completion
|
||||
|
||||
1. Ensure all changes committed on feature branch:
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "feat: implement RSS feed and production container (v0.6.0)"
|
||||
```
|
||||
2. Create PR to merge `feature/phase-5-rss-container` into main
|
||||
3. After merge, tag release on main:
|
||||
```bash
|
||||
git checkout main
|
||||
git pull
|
||||
git tag -a v0.6.0 -m "Release 0.6.0: RSS feed and production container"
|
||||
git push --tags
|
||||
```
|
||||
4. Create implementation report in `docs/reports/`
|
||||
5. Begin Phase 6 planning (Micropub implementation)
|
||||
|
||||
## Reference Documents
|
||||
|
||||
- [Phase 5 Full Design](/home/phil/Projects/starpunk/docs/designs/phase-5-rss-and-container.md)
|
||||
- [ADR-014: RSS Implementation](/home/phil/Projects/starpunk/docs/decisions/ADR-014-rss-feed-implementation.md)
|
||||
- [Versioning Strategy](/home/phil/Projects/starpunk/docs/standards/versioning-strategy.md)
|
||||
- [Git Branching Strategy](/home/phil/Projects/starpunk/docs/standards/git-branching-strategy.md)
|
||||
|
||||
---
|
||||
|
||||
**Phase**: 5
|
||||
**Version**: 0.6.0
|
||||
**Date**: 2025-11-18
|
||||
**Status**: Ready for Implementation
|
||||
1257
docs/designs/phase-5-rss-and-container.md
Normal file
1257
docs/designs/phase-5-rss-and-container.md
Normal file
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user