PhilandClaude Opus 5.5 952ca300c0 fix: keep GIFs moving in reply contexts (v2.20.1)
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>
2026-11-13 20:28:20 -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%