PhilandClaude Opus 5.5 b7f8e1612c feat: articles at /article/<slug> with slugs from their titles (v2.17.0, ADR-077)
Articles (notes with a title) move from /note/<slug> to /article/<slug>;
the other prefix 301-redirects. New articles take their slug from the
title (mp-slug still wins; notes keep timestamp slugs). A Micropub update
that adds or removes a title answers 201 with the new Location.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 12:27:31 -07:00
2025-11-18 19:21:31 -07:00
2026-11-03 13:43:39 -07:00

StarPunk

A minimal, self-hosted, single-user IndieWeb site for publishing notes. Flask, SQLite and markdown files; one container.

"Every line of code must justify its existence. When in doubt, leave it out."

The current version is in starpunk/__init__.py; what changed in each release is in CHANGELOG.md.

Features

Publishing

  • Notes in markdown, stored as plain files with metadata in SQLite
  • Admin editor with drafts, custom slugs, tags and photo uploads (resized variants, HEIC/MPO converted to JPEG, captions)
  • Post types: notes, titled posts, replies, likes, reposts and bookmarks
  • Full-text search (SQLite FTS5) and tag pages

IndieWeb

  • Micropub: create, update, delete and undelete; media endpoint; q=config, source, syndicate-to, category
  • Built-in IndieAuth server for Micropub apps (consent screen, tokens, revocation, Connected Apps page)
  • Admin login through any OpenID Connect provider (e.g. Pocket ID)
  • MCP server at /mcp so AI assistants (claude.ai connectors, Claude Code…) can search, read and write notes after you approve them, run as an optional sidecar (ADR-075)
  • Webmention: receiving (verified, moderated, rate-limited) and sending; replies, quotes and mentions shown on each note, with likes, reposts and replies as a line of counts with hover cards and <indie-action> web actions
  • WebSub with a built-in hub, so readers get new posts within seconds
  • Microformats2: h-entry, h-feed and an h-card discovered from your own site

Syndication

  • Feeds: RSS 2.0 (with Media RSS), Atom 1.0, JSON Feed 1.1, content negotiation at /feed, OPML export; tag pages and the likes page are h-feeds readers can follow
  • POSSE crossposting to GoToSocial/Mastodon, Bluesky and Threads, with u-syndication links back; edits and deletes follow, native likes and boosts where the target supports them
  • Backfeed: likes, reposts and replies to crossposts on GoToSocial and Bluesky (and Bluesky quotes), and replies on Threads (with its like and repost counts), come back as responses (BACKFEED_ENABLED, ADR-073)

Operations

  • Migrations applied automatically at startup
  • /health endpoint, /admin/health diagnostics, structured logs
  • Notifications of new responses and crossposting problems through Apprise (Gotify, ntfy, email…; NOTIFY_URLS, ADR-074)
  • Fetches of user-supplied URLs are limited to public addresses, size and time

Quick start

Container

git clone https://git.thesatelliteoflove.com/phil/StarPunk.git && cd StarPunk
cp .env.example .env      # set SITE_URL, ADMIN_ME, SESSION_SECRET, OIDC_*
docker build -t starpunk -f Containerfile .
docker run -d --name starpunk -p 127.0.0.1:8000:8000 --env-file .env \
  -v ./starpunk-data:/data starpunk

The container runs as UID 1000, so the data directory must be writable by it. Release images are published by CI as git.thesatelliteoflove.com/phil/starpunk:vX.Y.Z. Put a reverse proxy with HTTPS in front (see Caddyfile.example or nginx.conf.example) and set TRUSTED_PROXY=true. Register <SITE_URL>/auth/callback as the redirect URI with your OIDC provider. Details: docs/architecture/deployment.md.

Local development

uv venv --python 3.14
uv pip install -r requirements-dev.txt
cp .env.example .env      # set SESSION_SECRET; add DEV_MODE=true and DEV_ADMIN_ME
uv run flask --app app.py run --debug                  # http://localhost:5000
SESSION_SECRET=test uv run pytest tests/test_<area>.py  # tests for what you changed; CI runs the full suite

With DEV_MODE=true, /dev/login logs you in without OIDC. Never enable it on a public server. Full guide: docs/standards/development-setup.md.

Configuration

All settings are environment variables (or a .env file), each listed with its default in .env.example. Required in production: SESSION_SECRET, SITE_URL, ADMIN_ME, OIDC_ISSUER, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET and OIDC_ADMIN_SUB. Crossposting is enabled by setting a target's credentials. Backfeed is off unless BACKFEED_ENABLED=true; notifications start when NOTIFY_URLS is set.

Data and backups

Everything lives in the data directory (/data in the container): the SQLite database, note files in notes/, uploaded media, saved response avatars in avatars/, the Threads token (threads_token.json) and logs. Back it up regularly, and always before upgrading to a release with a migration.

Documentation

Topic Where
How the docs are organized docs/DOCUMENTATION.md
System overview docs/architecture/overview.md
Technology stack docs/architecture/technology-stack.md
Database and migrations docs/architecture/database.md
Deployment docs/architecture/deployment.md
Authentication (OIDC, IndieAuth) docs/architecture/simplified-auth-architecture.md
IndieWeb protocols docs/architecture/indieweb-protocols.md
Feeds and crossposting docs/architecture/syndication-architecture.md
Decisions (ADRs) docs/decisions/INDEX.md
Per-release designs and reports docs/design/
Backlog docs/projectplan/BACKLOG.md
Development standards and release process docs/standards/INDEX.md

License

MIT: use, change and share it for anything, including commercially, as long as the copyright and license notice stay with it.

S
Description
No description provided
Readme MIT
6.4 MiB
0 Stars 1 Watchers 0 Forks
Languages
Python 94.3%
HTML 4%
CSS 1.5%
Dockerfile 0.2%