Mastodon turns GIFs into silent looping MP4s (gifv); only the first-frame preview was kept. The MP4 is now saved locally and played muted and looping with the still as poster. Animated GIFs from other sites are saved as animated WebP. Migration 025 adds reply_contexts.video and has fediverse contexts with an image fetched again once. 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.