StarPunk/docs/operations/upgrade-to-v1.1.2.md

Upgrade Guide: StarPunk v1.1.2 "Syndicate"

Release Date: 2025-11-27 Previous Version: v1.1.1 Target Version: v1.1.2-rc.1

Overview

StarPunk v1.1.2 "Syndicate" adds multi-format feed support with content negotiation, caching, and comprehensive monitoring. This release is 100% backward compatible with v1.1.1 - no breaking changes.

Key Features

• Multi-Format Feeds: RSS 2.0, ATOM 1.0, JSON Feed 1.1 support
• Content Negotiation: Smart format selection via HTTP Accept headers
• Feed Caching: LRU cache with TTL and ETag support
• Feed Statistics: Real-time monitoring dashboard
• OPML Export: Subscription list for feed readers
• Metrics Instrumentation: Complete monitoring foundation

What's New in v1.1.2

Phase 1: Metrics Instrumentation

• Database operation monitoring with query timing
• HTTP request/response metrics with request IDs
• Memory monitoring daemon thread
• Business metrics framework
• Configuration management

Phase 2: Multi-Format Feeds

• RSS 2.0: Fixed ordering bug, streaming + non-streaming generation
• ATOM 1.0: RFC 4287 compliant with proper XML namespacing
• JSON Feed 1.1: Spec compliant with custom _starpunk extension
• Content negotiation via Accept headers
• Multiple endpoints: /feed, /feed.rss, /feed.atom, /feed.json

Phase 3: Feed Enhancements

• LRU cache with 5-minute TTL
• ETag support with 304 Not Modified responses
• Feed statistics on admin dashboard
• OPML 2.0 export at /opml.xml
• Feed discovery links in HTML

Prerequisites

Before upgrading:

1. Backup your data:

   # Backup database
   cp data/starpunk.db data/starpunk.db.backup
   
   # Backup notes
   cp -r data/notes data/notes.backup
   

2. Check current version:

   uv run python -c "import starpunk; print(starpunk.__version__)"
   

3. Review changelog: Read CHANGELOG.md for detailed changes

Upgrade Steps

Step 1: Stop StarPunk

If running in production:

# For systemd service
sudo systemctl stop starpunk

# For container deployment
podman stop starpunk  # or docker stop starpunk

Step 2: Pull Latest Code

# From git repository
git fetch origin
git checkout v1.1.2-rc.1

# Or download release tarball
wget https://github.com/YOUR_USERNAME/starpunk/archive/v1.1.2-rc.1.tar.gz
tar xzf v1.1.2-rc.1.tar.gz
cd starpunk-1.1.2-rc.1

Step 3: Update Dependencies

# Update Python dependencies with uv
uv sync

Note: v1.1.2 requires psutil for memory monitoring. This will be installed automatically.

Step 4: Verify Configuration

No new required configuration variables in v1.1.2, but you can optionally configure new features:

# Optional: Disable metrics (default: enabled)
export METRICS_ENABLED=true

# Optional: Configure metrics sampling rates
export METRICS_SAMPLING_DATABASE=1.0    # 100% of database operations
export METRICS_SAMPLING_HTTP=0.1        # 10% of HTTP requests
export METRICS_SAMPLING_RENDER=0.1      # 10% of template renders

# Optional: Configure memory monitoring interval (default: 30 seconds)
export METRICS_MEMORY_INTERVAL=30

# Optional: Disable feed caching (default: enabled)
export FEED_CACHE_ENABLED=true

# Optional: Configure feed cache size (default: 50 entries)
export FEED_CACHE_MAX_SIZE=50

# Optional: Configure feed cache TTL (default: 300 seconds / 5 minutes)
export FEED_CACHE_SECONDS=300

Step 5: Run Database Migrations

StarPunk uses automatic migrations - no manual SQL needed:

# Migrations run automatically on startup
# No database schema changes in v1.1.2
uv run python -c "from starpunk import create_app; app = create_app(); print('Database ready')"

Step 6: Restart StarPunk

# For systemd service
sudo systemctl start starpunk
sudo systemctl status starpunk

# For container deployment
podman start starpunk  # or docker start starpunk

# For development
uv run flask run

Step 7: Verify Upgrade

1. Check version:

   uv run python -c "import starpunk; print(starpunk.__version__)"
   # Should output: 1.1.2-rc.1
   

2. Test health endpoint:

   curl http://localhost:5000/health
   # Should return: {"status":"ok","version":"1.1.2-rc.1"}
   

3. Test feed endpoints:

   # RSS feed
   curl http://localhost:5000/feed.rss
   
   # ATOM feed
   curl http://localhost:5000/feed.atom
   
   # JSON Feed
   curl http://localhost:5000/feed.json
   
   # Content negotiation
   curl -H "Accept: application/atom+xml" http://localhost:5000/feed
   
   # OPML export
   curl http://localhost:5000/opml.xml
   

4. Check metrics dashboard (requires authentication):

   # Visit http://localhost:5000/admin/metrics-dashboard
   # Should show feed statistics section
   

5. Run test suite (optional):

   uv run pytest
   # Should show: 766 tests passing
   

New Features and Endpoints

Multi-Format Feed Endpoints

• /feed - Content negotiation endpoint (respects Accept header)
• /feed.rss or /feed.xml - Explicit RSS 2.0 feed
• /feed.atom - Explicit ATOM 1.0 feed
• /feed.json - Explicit JSON Feed 1.1
• /opml.xml - OPML 2.0 subscription list

Content Negotiation

The /feed endpoint now supports HTTP content negotiation:

# Request ATOM feed
curl -H "Accept: application/atom+xml" http://localhost:5000/feed

# Request JSON Feed
curl -H "Accept: application/json" http://localhost:5000/feed

# Request RSS feed (default)
curl -H "Accept: */*" http://localhost:5000/feed

Feed Caching

All feed endpoints now support:

• ETag headers for conditional requests
• 304 Not Modified responses for unchanged content
• LRU cache with 5-minute TTL (configurable)
• Cache statistics on admin dashboard

Example:

# First request - generates feed and returns ETag
curl -i http://localhost:5000/feed.rss
# Response: ETag: W/"abc123..."

# Subsequent request with If-None-Match
curl -H 'If-None-Match: W/"abc123..."' http://localhost:5000/feed.rss
# Response: 304 Not Modified (no body, saves bandwidth)

Feed Statistics Dashboard

Visit /admin/metrics-dashboard to see:

• Requests by format (RSS, ATOM, JSON Feed)
• Cache hit/miss rates
• Feed generation performance
• Format popularity (pie chart)
• Cache efficiency (doughnut chart)
• Auto-refresh every 10 seconds

OPML Subscription List

The /opml.xml endpoint provides an OPML 2.0 subscription list containing all three feed formats:

• No authentication required (public)
• Compatible with all major feed readers
• Discoverable via <link> tag in HTML

Performance Improvements

Feed Generation

• RSS streaming: Memory-efficient generation for large feeds
• ATOM streaming: RFC 4287 compliant streaming output
• JSON streaming: Line-by-line JSON generation
• Generation time: 2-5ms for 50 items

Caching Benefits

• Bandwidth savings: 304 responses for repeat requests
• Cache overhead: <1ms per request
• Memory bounded: LRU cache limited to 50 entries
• TTL: 5-minute cache lifetime (configurable)

Metrics Overhead

• Database monitoring: Negligible overhead with connection pooling
• HTTP metrics: 10% sampling (configurable)
• Memory monitoring: Background daemon thread (30s interval)

Breaking Changes

None. This release is 100% backward compatible with v1.1.1.

Deprecated Features

• /feed.xml redirect: Still works but /feed.rss is preferred
• Old /feed endpoint: Now supports content negotiation (still defaults to RSS)

Rollback Procedure

If you need to rollback to v1.1.1:

# Stop StarPunk
sudo systemctl stop starpunk  # or podman stop starpunk

# Checkout v1.1.1
git checkout v1.1.1

# Restore dependencies
uv sync

# Restore database backup (if needed)
cp data/starpunk.db.backup data/starpunk.db

# Restart StarPunk
sudo systemctl start starpunk  # or podman start starpunk

Note: No database schema changes in v1.1.2, so rollback is safe.

Known Issues

None at this time. This is a release candidate - please report any issues.

Getting Help

• Documentation: Check /docs/ for detailed documentation
• Troubleshooting: See docs/operations/troubleshooting.md
• GitHub Issues: Report bugs and request features
• Changelog: See CHANGELOG.md for detailed change history

What's Next

After v1.1.2 stable release:

• v1.2.0: Advanced features (Webmentions, media uploads)
• v2.0.0: Multi-user support and significant architectural changes

See docs/projectplan/ROADMAP.md for complete roadmap.

---

Upgrade completed successfully!

Your StarPunk instance now supports multi-format feeds with caching and comprehensive monitoring.