Replies to Mastodon posts showed only the server's domain: the page has no h-entry, so nothing was found and the host stood in for the author. - Context sources in order: Bluesky AppView API, microformats, the origin's Mastodon API or this site's GoToSocial instance, OpenGraph - Migration 024: author_handle, photo, photo_alt, source; rows without a source are fetched again once by the webmention worker - Note page: a card with avatar, name, handle, text, image and date; home/tag/likes: "In reply to <author>" with a short quote - Avatars and images saved locally (CSP allows only this site's images); avatar upkeep now covers reply contexts so their avatars aren't removed Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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
/mcpso 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-syndicationlinks 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
/healthendpoint,/admin/healthdiagnostics, 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.