- Connect to the address that passed the SSRF check (Host header and SNI carry the hostname, so TLS still verifies it), closing the DNS rebinding gap (spec 4.5). The webmention POST uses the same path. - Treat a change in the responses a note shows as an update and re-send its webmentions (spec 3.1.4), from validation and from admin moderation. Unchanged re-validations send nothing, so there is no ping-pong. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
StarPunk
A minimal, self-hosted IndieWeb CMS for publishing notes with RSS syndication.
Current Version: 1.2.0
Versioning
StarPunk follows Semantic Versioning 2.0.0:
- Version format:
MAJOR.MINOR.PATCH - Current:
1.2.0(stable release) - Check version:
python -c "from starpunk import __version__; print(__version__)" - See changes: CHANGELOG.md
- Versioning strategy: docs/standards/versioning-strategy.md
Philosophy
"Every line of code must justify its existence. When in doubt, leave it out."
StarPunk is designed for a single user who wants to:
- Publish short notes to their personal website
- Own their content (notes stored as portable markdown files)
- Syndicate via RSS
- Support IndieWeb standards (Micropub, IndieAuth)
- Run on minimal resources
Features
- File-based storage: Notes are markdown files, owned by you
- OIDC admin login: Sign in through your identity provider (e.g. Pocket ID)
- Built-in IndieAuth server: Approve Micropub apps without a separate auth service
- Micropub support: Full W3C Micropub specification compliance
- Media attachments: Upload and display images with your notes
- Microformats2: Full h-entry, h-card, and h-feed markup for IndieWeb compatibility
- Author discovery: Automatic profile discovery from your IndieWeb identity
- RSS, ATOM, JSON Feed: Multiple syndication formats with Media RSS support
- Custom slugs: Control your note permalinks
- No database lock-in: SQLite for metadata, files for content
- Self-hostable: Run on your own server
- Minimal dependencies: Core dependencies, no build tools
Requirements
- Python 3.11 or higher
- 500MB disk space
- Linux, macOS, or Windows with WSL2
Quick Start
# Clone repository
git clone https://github.com/YOUR_USERNAME/starpunk.git
cd starpunk
# Install uv (package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh
# Create virtual environment
uv venv .venv --python 3.11
# Install dependencies
uv pip install -r requirements.txt
# Configure
cp .env.example .env
# Edit .env and set ADMIN_ME, SESSION_SECRET and the OIDC_* values
# Initialize database
mkdir -p data/notes
.venv/bin/python -c "from starpunk.database import init_db; init_db()"
# Note: Database also auto-initializes on first run if not present
# Run development server
.venv/bin/flask --app app.py run --debug
# Visit http://localhost:5000
Configuration
All configuration is in the .env file. Required settings:
ADMIN_ME- Your IndieWeb identity URL (e.g., https://yoursite.com)SESSION_SECRET- Random secret key (generate withpython3 -c "import secrets; print(secrets.token_hex(32))")SITE_URL- Public URL of your siteOIDC_ISSUER,OIDC_CLIENT_ID,OIDC_CLIENT_SECRET- OIDC client for admin login (callback:<SITE_URL>/auth/callback)OIDC_ADMIN_SUB- Subject ID of the one account allowed to log in
See .env.example for all options.
Project Structure
starpunk/
├── app.py # Application entry point
├── starpunk/ # Application code
├── data/ # Your notes and database (gitignored)
│ ├── notes/ # Markdown files
│ └── starpunk.db # SQLite database
├── static/ # CSS and JavaScript
├── templates/ # HTML templates
└── tests/ # Test suite
Usage
Publishing Notes
Via Web Interface:
- Navigate to
/admin - Login with your IndieWeb identity
- Create notes in markdown
Via Micropub Client:
- Configure client with your site URL
- Sign in with your OIDC provider
- Publish from any Micropub-compatible app
Backing Up Your Data
Your notes are stored as plain markdown files in data/notes/. Back up this directory:
# Simple backup
tar -czf backup.tar.gz data/
# Or use rsync
rsync -av data/ /backup/starpunk/
Development
See docs/standards/development-setup.md for detailed setup.
# Install dev dependencies
uv pip install -r requirements-dev.txt
# Run tests
.venv/bin/pytest
# Format code
.venv/bin/black starpunk/ tests/
# Lint
.venv/bin/flake8 starpunk/ tests/
Architecture
StarPunk uses a hybrid storage approach:
- Notes content: Markdown files (portable, human-readable)
- Metadata: SQLite database (fast queries)
This gives you both portability AND performance.
See docs/architecture/ for complete documentation.
IndieWeb Compliance
StarPunk implements:
- Micropub - Publishing API
- IndieAuth - Authentication
- Microformats2 - h-entry, h-card, h-feed markup
- RSS 2.0 with Media RSS extensions
- ATOM 1.0 - Syndication format
- JSON Feed 1.1 - Modern feed format
Deployment
Production Setup
# Install gunicorn
uv pip install gunicorn
# Run with gunicorn
.venv/bin/gunicorn -w 4 -b 127.0.0.1:8000 app:app
# Configure nginx/Caddy for HTTPS
# Set up systemd for process management
# Enable regular backups of data/ directory
See docs/standards/deployment-standards.md for details.
License
MIT License - see LICENSE file
Credits
Built with:
- Flask - Web framework
- python-markdown - Markdown processing
- feedgen - RSS generation
- httpx - HTTP client
Contributing
This is a personal project optimized for single-user use. If you want additional features, consider forking!
Support
- Documentation: docs/
- Issues: GitHub Issues
- IndieWeb: indieweb.org