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
• IndieAuth authentication: Use your own website as identity
• 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 and SESSION_SECRET

# 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 with python3 -c "import secrets; print(secrets.token_hex(32))")
• SITE_URL - Public URL of your site

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:

1. Navigate to /admin
2. Login with your IndieWeb identity
3. Create notes in markdown

Via Micropub Client:

1. Configure client with your site URL
2. Authenticate via IndieAuth
3. 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
• IndieLogin - Authentication service

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