phil/StarPunk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: Complete v1.1.1 Phases 2 & 3 - Enhancements and Polish

Browse Source 
Phase 2 - Enhancements:
- Add performance monitoring infrastructure with MetricsBuffer
- Implement three-tier health checks (/health, /health?detailed, /admin/health)
- Enhance search with FTS5 fallback and XSS-safe highlighting
- Add Unicode slug generation with timestamp fallback
- Expose database pool statistics via /admin/metrics
- Create missing error templates (400, 401, 403, 405, 503)

Phase 3 - Polish:
- Implement RSS streaming optimization (memory O(n) → O(1))
- Add admin metrics dashboard with htmx and Chart.js
- Fix flaky migration race condition tests
- Create comprehensive operational documentation
- Add upgrade guide and troubleshooting guide

Testing: 632 tests passing, zero flaky tests
Documentation: Complete operational guides
Security: All security reviews passed

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Phil Skentelbery
2025-11-25 20:10:41 -07:00
parent 93d2398c1d
commit 07fff01fab
25 changed files with 4371 additions and 142 deletions
Download Patch File Download Diff File Expand all files Collapse all files

528
docs/operations/troubleshooting.md Normal file
View File

@@ -0,0 +1,528 @@
# StarPunk Troubleshooting Guide
**Version**: 1.1.1
**Last Updated**: 2025-11-25
This guide helps diagnose and resolve common issues with StarPunk.
## Quick Diagnostics
### Check System Health
```bash
# Basic health check
curl http://localhost:5000/health
# Detailed health check (requires authentication)
curl -H "Authorization: Bearer YOUR_TOKEN" \
http://localhost:5000/health?detailed=true
# Full diagnostics
curl -H "Authorization: Bearer YOUR_TOKEN" \
http://localhost:5000/admin/health
```
### Check Logs
```bash
# View recent logs
tail -f data/logs/starpunk.log
# Search for errors
grep ERROR data/logs/starpunk.log | tail -20
# Search for warnings
grep WARNING data/logs/starpunk.log | tail -20
```
### Check Database
```bash
# Verify database exists and is accessible
ls -lh data/starpunk.db
# Check database integrity
sqlite3 data/starpunk.db "PRAGMA integrity_check;"
# Check migrations
sqlite3 data/starpunk.db "SELECT * FROM schema_migrations;"
```
## Common Issues
### Application Won't Start
#### Symptom
StarPunk fails to start or crashes immediately.
#### Possible Causes
1. **Missing configuration**
```bash
# Check required environment variables
echo $SITE_URL
echo $SITE_NAME
echo $ADMIN_ME
```
**Solution**: Set all required variables in `.env`:
```bash
SITE_URL=https://your-domain.com/
SITE_NAME=Your Site Name
ADMIN_ME=https://your-domain.com/
```
2. **Database locked**
```bash
# Check for other processes
lsof data/starpunk.db
```
**Solution**: Stop other StarPunk instances or wait for lock release
3. **Permission issues**
```bash
# Check permissions
ls -ld data/
ls -l data/starpunk.db
```
**Solution**: Fix permissions:
```bash
chmod 755 data/
chmod 644 data/starpunk.db
```
4. **Missing dependencies**
```bash
# Re-sync dependencies
uv sync
```
### Database Connection Errors
#### Symptom
Errors like "database is locked" or "unable to open database file"
#### Solutions
1. **Check database path**
```bash
# Verify DATABASE_PATH in config
echo $DATABASE_PATH
ls -l $DATABASE_PATH
```
2. **Check file permissions**
```bash
# Database file needs write permission
chmod 644 data/starpunk.db
chmod 755 data/
```
3. **Check disk space**
```bash
df -h
```
4. **Check connection pool**
```bash
# View pool statistics
curl http://localhost:5000/admin/metrics | jq '.database.pool'
```
If pool is exhausted, increase `DB_POOL_SIZE`:
```bash
export DB_POOL_SIZE=10
```
### IndieAuth Login Fails
#### Symptom
Cannot log in to admin interface, redirects fail, or authentication errors.
#### Solutions
1. **Check ADMIN_ME configuration**
```bash
echo $ADMIN_ME
```
Must be a valid URL that matches your identity.
2. **Check IndieAuth endpoints**
```bash
# Verify endpoints are discoverable
curl -I $ADMIN_ME | grep Link
```
Should show authorization_endpoint and token_endpoint.
3. **Check callback URL**
- Verify `/auth/callback` is accessible
- Check for HTTPS in production
- Verify no trailing slash issues
4. **Check session secret**
```bash
echo $SESSION_SECRET
```
Must be set and persistent across restarts.
### RSS Feed Issues
#### Symptom
Feed not displaying, validation errors, or empty feed.
#### Solutions
1. **Check feed endpoint**
```bash
curl http://localhost:5000/feed.xml | head -50
```
2. **Verify published notes**
```bash
sqlite3 data/starpunk.db \
"SELECT COUNT(*) FROM notes WHERE published=1;"
```
3. **Check feed cache**
```bash
# Clear cache by restarting
# Cache duration controlled by FEED_CACHE_SECONDS
```
4. **Validate feed**
```bash
curl http://localhost:5000/feed.xml | \
xmllint --format - | head -100
```
### Search Not Working
#### Symptom
Search returns no results or errors.
#### Solutions
1. **Check FTS5 availability**
```bash
sqlite3 data/starpunk.db \
"SELECT COUNT(*) FROM notes_fts;"
```
2. **Rebuild search index**
```bash
uv run python -c "from starpunk.search import rebuild_fts_index; \
rebuild_fts_index('data/starpunk.db', 'data')"
```
3. **Check for FTS5 support**
```bash
sqlite3 data/starpunk.db \
"PRAGMA compile_options;" | grep FTS5
```
If not available, StarPunk will fall back to LIKE queries automatically.
### Performance Issues
#### Symptom
Slow response times, high memory usage, or timeouts.
#### Diagnostics
1. **Check performance metrics**
```bash
curl http://localhost:5000/admin/metrics | jq '.performance'
```
2. **Check database pool**
```bash
curl http://localhost:5000/admin/metrics | jq '.database.pool'
```
3. **Check system resources**
```bash
# Memory usage
ps aux | grep starpunk
# Disk usage
df -h
# Open files
lsof -p $(pgrep -f starpunk)
```
#### Solutions
1. **Increase connection pool**
```bash
export DB_POOL_SIZE=10
```
2. **Adjust metrics sampling**
```bash
# Reduce sampling for high-traffic sites
export METRICS_SAMPLING_HTTP=0.01 # 1% sampling
export METRICS_SAMPLING_RENDER=0.01
```
3. **Increase cache duration**
```bash
export FEED_CACHE_SECONDS=600 # 10 minutes
```
4. **Check slow queries**
```bash
grep "SLOW" data/logs/starpunk.log
```
### Log Rotation Not Working
#### Symptom
Log files growing unbounded, disk space issues.
#### Solutions
1. **Check log directory**
```bash
ls -lh data/logs/
```
2. **Verify log rotation configuration**
- RotatingFileHandler configured for 10MB files
- Keeps 10 backup files
- Automatic rotation on size limit
3. **Manual log rotation**
```bash
# Backup and truncate
mv data/logs/starpunk.log data/logs/starpunk.log.old
touch data/logs/starpunk.log
chmod 644 data/logs/starpunk.log
```
4. **Check permissions**
```bash
ls -l data/logs/
chmod 755 data/logs/
chmod 644 data/logs/*.log
```
### Metrics Dashboard Not Loading
#### Symptom
Blank dashboard, 404 errors, or JavaScript errors.
#### Solutions
1. **Check authentication**
- Must be logged in as admin
- Navigate to `/admin/dashboard`
2. **Check JavaScript console**
- Open browser developer tools
- Look for CDN loading errors
- Verify htmx and Chart.js load
3. **Check network connectivity**
```bash
# Test CDN access
curl -I https://unpkg.com/htmx.org@1.9.10
curl -I https://cdn.jsdelivr.net/npm/chart.js@4.4.0/dist/chart.umd.min.js
```
4. **Test metrics endpoint**
```bash
curl http://localhost:5000/admin/metrics
```
## Log File Locations
- **Application logs**: `data/logs/starpunk.log`
- **Rotated logs**: `data/logs/starpunk.log.1` through `starpunk.log.10`
- **Container logs**: `podman logs starpunk` or `docker logs starpunk`
- **System logs**: `/var/log/syslog` or `journalctl -u starpunk`
## Health Check Interpretation
### Basic Health (`/health`)
```json
{
"status": "healthy"
}
```
- **healthy**: All systems operational
- **unhealthy**: Critical issues detected
### Detailed Health (`/health?detailed=true`)
```json
{
"status": "healthy",
"version": "1.1.1",
"checks": {
"database": {"status": "healthy"},
"filesystem": {"status": "healthy"},
"fts_index": {"status": "healthy"}
}
}
```
Check each component status individually.
### Full Diagnostics (`/admin/health`)
Includes all above plus:
- Performance metrics
- Database pool statistics
- System resource usage
- Error budget status
## Performance Monitoring Tips
### Normal Metrics
- **Database queries**: avg < 50ms
- **HTTP requests**: avg < 200ms
- **Template rendering**: avg < 50ms
- **Pool usage**: < 80% connections active
### Warning Signs
- **Database**: avg > 100ms consistently
- **HTTP**: avg > 500ms
- **Pool**: 100% connections active
- **Memory**: continuous growth
### Metrics Sampling
Adjust sampling rates based on traffic:
```bash
# Low traffic (< 100 req/day)
METRICS_SAMPLING_DATABASE=1.0
METRICS_SAMPLING_HTTP=1.0
METRICS_SAMPLING_RENDER=1.0
# Medium traffic (100-1000 req/day)
METRICS_SAMPLING_DATABASE=1.0
METRICS_SAMPLING_HTTP=0.1
METRICS_SAMPLING_RENDER=0.1
# High traffic (> 1000 req/day)
METRICS_SAMPLING_DATABASE=0.1
METRICS_SAMPLING_HTTP=0.01
METRICS_SAMPLING_RENDER=0.01
```
## Database Pool Issues
### Pool Exhaustion
**Symptom**: "No available connections" errors
**Solution**:
```bash
# Increase pool size
export DB_POOL_SIZE=10
# Or reduce request concurrency
```
### Pool Leaks
**Symptom**: Connections not returned to pool
**Check**:
```bash
curl http://localhost:5000/admin/metrics | \
jq '.database.pool'
```
Look for high `active_connections` that don't decrease.
**Solution**: Restart application to reset pool
## Getting Help
### Before Filing an Issue
1. Check this troubleshooting guide
2. Review logs for specific errors
3. Run health checks
4. Try with minimal configuration
5. Search existing issues
### Information to Include
When filing an issue, include:
1. **Version**: `uv run python -c "import starpunk; print(starpunk.__version__)"`
2. **Environment**: Development or production
3. **Configuration**: Sanitized `.env` (remove secrets)
4. **Logs**: Recent errors from `data/logs/starpunk.log`
5. **Health check**: Output from `/admin/health`
6. **Steps to reproduce**: Exact commands that trigger the issue
### Debug Mode
Enable verbose logging:
```bash
export LOG_LEVEL=DEBUG
# Restart StarPunk
```
**WARNING**: Debug logs may contain sensitive information. Don't share publicly.
## Emergency Recovery
### Complete Reset (DESTRUCTIVE)
**WARNING**: This deletes all data.
```bash
# Stop StarPunk
sudo systemctl stop starpunk
# Backup everything
cp -r data data.backup.$(date +%Y%m%d)
# Remove database
rm data/starpunk.db
# Remove logs
rm -rf data/logs/
# Restart (will reinitialize)
sudo systemctl start starpunk
```
### Restore from Backup
```bash
# Stop StarPunk
sudo systemctl stop starpunk
# Restore database
cp data.backup/starpunk.db data/
# Restore notes
cp -r data.backup/notes/* data/notes/
# Restart
sudo systemctl start starpunk
```
## Related Documentation
- `/docs/operations/upgrade-to-v1.1.1.md` - Upgrade procedures
- `/docs/operations/performance-tuning.md` - Optimization guide
- `/docs/architecture/overview.md` - System architecture
- `CHANGELOG.md` - Version history and changes

315
docs/operations/upgrade-to-v1.1.1.md Normal file
View File

@@ -0,0 +1,315 @@
# Upgrade Guide: StarPunk v1.1.1 "Polish"
**Release Date**: 2025-11-25
**Previous Version**: v1.1.0
**Target Version**: v1.1.1
## Overview
StarPunk v1.1.1 "Polish" is a maintenance release focused on production readiness, performance optimization, and operational improvements. This release is **100% backward compatible** with v1.1.0 - no breaking changes.
### Key Improvements
- **RSS Memory Optimization**: Streaming feed generation for large feeds
- **Performance Monitoring**: MetricsBuffer with database pool statistics
- **Enhanced Health Checks**: Three-tier health check system
- **Search Improvements**: FTS5 fallback and result highlighting
- **Unicode Slug Support**: Better international character handling
- **Admin Dashboard**: Visual metrics and monitoring interface
- **Memory Monitoring**: Background thread for system metrics
- **Logging Improvements**: Proper log rotation verification
## Prerequisites
Before upgrading:
1. **Backup your data**:
```bash
# Backup database
cp data/starpunk.db data/starpunk.db.backup
# Backup notes
cp -r data/notes data/notes.backup
```
2. **Check current version**:
```bash
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:
```bash
# For systemd service
sudo systemctl stop starpunk
# For container deployment
podman stop starpunk # or docker stop starpunk
```
### Step 2: Pull Latest Code
```bash
# From git repository
git fetch origin
git checkout v1.1.1
# Or download release tarball
wget https://github.com/YOUR_USERNAME/starpunk/archive/v1.1.1.tar.gz
tar xzf v1.1.1.tar.gz
cd starpunk-1.1.1
```
### Step 3: Update Dependencies
```bash
# Update Python dependencies with uv
uv sync
```
### Step 4: Verify Configuration
No new required configuration variables in v1.1.1, but you can optionally configure new features:
```bash
# Optional: Adjust feed caching (default: 300 seconds)
export FEED_CACHE_SECONDS=300
# Optional: Adjust database pool size (default: 5)
export DB_POOL_SIZE=5
# Optional: Adjust metrics sampling rates
export METRICS_SAMPLING_DATABASE=1.0
export METRICS_SAMPLING_HTTP=0.1
export METRICS_SAMPLING_RENDER=0.1
```
### Step 5: Run Database Migrations
StarPunk uses automatic migrations - no manual SQL needed:
```bash
# Migrations run automatically on startup
# Verify migration status:
uv run python -c "from starpunk.database import init_db; init_db()"
```
Expected output:
```
INFO [init]: Database initialized: data/starpunk.db
INFO [init]: No pending migrations
INFO [init]: Database connection pool initialized (size=5)
```
### Step 6: Verify Installation
Run the test suite to ensure everything works:
```bash
# Run tests (should see 600+ tests passing)
uv run pytest
```
### Step 7: Restart StarPunk
```bash
# For systemd service
sudo systemctl start starpunk
sudo systemctl status starpunk
# For container deployment
podman start starpunk # or docker start starpunk
podman logs -f starpunk
```
### Step 8: Verify Upgrade
1. **Check version**:
```bash
curl https://your-domain.com/health
```
Should show version "1.1.1"
2. **Test admin dashboard**:
- Log in to admin interface
- Navigate to "Metrics" tab
- Verify charts and statistics display correctly
3. **Test RSS feed**:
```bash
curl https://your-domain.com/feed.xml | head -20
```
Should return valid XML with streaming response
4. **Check logs**:
```bash
tail -f data/logs/starpunk.log
```
Should show clean startup with no errors
## New Features
### Admin Metrics Dashboard
Access the new metrics dashboard at `/admin/dashboard`:
- Real-time performance metrics
- Database connection pool statistics
- Auto-refresh every 10 seconds (requires JavaScript)
- Progressive enhancement (works without JavaScript)
- Charts powered by Chart.js
### RSS Feed Optimization
The RSS feed now uses streaming for better memory efficiency:
- Memory usage reduced from O(n) to O(1)
- Lower time-to-first-byte for large feeds
- Cache stores note list, not full XML
- Transparent to clients (no API changes)
### Enhanced Health Checks
Three tiers of health checks available:
1. **Basic** (`/health`): Public, minimal response
2. **Detailed** (`/health?detailed=true`): Authenticated, comprehensive
3. **Full Diagnostics** (`/admin/health`): Authenticated, includes metrics
### Search Improvements
- FTS5 detection at startup
- Graceful fallback to LIKE queries if FTS5 unavailable
- Search result highlighting with XSS prevention
### Unicode Slug Support
- Unicode normalization (NFKD) for international characters
- Timestamp-based fallback for untranslatable text
- Never fails Micropub requests due to slug issues
## Configuration Changes
### No Breaking Changes
All existing configuration continues to work. New optional variables:
```bash
# Performance tuning (all optional)
FEED_CACHE_SECONDS=300 # RSS feed cache duration
DB_POOL_SIZE=5 # Database connection pool size
METRICS_SAMPLING_DATABASE=1.0 # Sample 100% of DB operations
METRICS_SAMPLING_HTTP=0.1 # Sample 10% of HTTP requests
METRICS_SAMPLING_RENDER=0.1 # Sample 10% of template renders
```
### Removed Configuration
None. All v1.1.0 configuration variables continue to work.
## Rollback Procedure
If you encounter issues, rollback to v1.1.0:
### Step 1: Stop StarPunk
```bash
sudo systemctl stop starpunk # or podman/docker stop
```
### Step 2: Restore Previous Version
```bash
# Restore from git
git checkout v1.1.0
# Or restore from backup
cd /path/to/backup
cp -r starpunk-1.1.0/* /path/to/starpunk/
```
### Step 3: Restore Database (if needed)
```bash
# Only if database issues occurred
cp data/starpunk.db.backup data/starpunk.db
```
### Step 4: Restart
```bash
sudo systemctl start starpunk
```
## Common Issues
### Issue: Log Rotation Not Working
**Symptom**: Log files growing unbounded
**Solution**:
1. Check log file permissions
2. Verify `data/logs/` directory exists
3. Check `LOG_LEVEL` configuration
4. See `docs/operations/troubleshooting.md`
### Issue: Metrics Dashboard Not Loading
**Symptom**: 404 or blank metrics page
**Solution**:
1. Clear browser cache
2. Verify you're logged in as admin
3. Check browser console for JavaScript errors
4. Verify htmx and Chart.js CDN accessible
### Issue: RSS Feed Validation Errors
**Symptom**: Feed validators report errors
**Solution**:
1. Streaming implementation is RSS 2.0 compliant
2. Verify XML structure with validator
3. Check for special characters in note content
4. See `docs/operations/troubleshooting.md`
## Performance Tuning
See `docs/operations/performance-tuning.md` for detailed guidance on:
- Database pool sizing
- Metrics sampling rates
- Cache configuration
- Log rotation settings
## Support
If you encounter issues:
1. Check `docs/operations/troubleshooting.md`
2. Review logs in `data/logs/starpunk.log`
3. Run health checks: `curl /admin/health`
4. File issue on GitHub with logs and configuration
## Next Steps
After upgrading:
1. **Review new metrics**: Check `/admin/dashboard` regularly
2. **Adjust sampling**: Tune metrics sampling for your workload
3. **Monitor performance**: Use health endpoints for monitoring
4. **Update documentation**: Review operational guides
5. **Plan for v1.2.0**: Review roadmap for upcoming features
## Version History
- **v1.1.1 (2025-11-25)**: Polish release (current)
- **v1.1.0 (2025-11-25)**: Search and custom slugs
- **v1.0.1 (2025-11-25)**: Bug fixes
- **v1.0.0 (2025-11-24)**: First production release