PhilandClaude Opus 5.5 75946be7b2 maint: Dependency upgrades and High backlog items (v2.11.0)
- All dependencies to current releases (97 known vulnerabilities -> 0),
  Python 3.14, uv pinned, requirements-test.txt, lxml/dateutil pinned
- CSRF tokens on admin forms, logout and IndieAuth consent
- IndieAuth client and crosspost link-card fetches via safe_get
- FLASK_DEBUG/FLASK_ENV default off/production; image sets them
- Foreign keys enforced on pooled connections; migration 018 removes orphans
- Rate limits shared across processes (rate_limits, migration 019)
- datetime.utcnow() and sqlite3 default adapters replaced
- compose.yaml fixed; duplicate dev_auth.py and test.ini removed

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-03 13:09:52 -07:00
2025-11-18 19:21:31 -07:00
2025-11-18 19:21:31 -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)
  • Webmention: receiving (verified, moderated, rate-limited) and sending; replies, likes and reposts shown on each note
  • 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

Operations

  • Migrations applied automatically at startup
  • /health endpoint, admin metrics dashboard, structured logs
  • 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 \
  -e FLASK_ENV=production -e FLASK_DEBUG=0 \
  -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 (about 6 minutes)

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.

Data and backups

Everything lives in the data directory (/data in the container): the SQLite database, note files in notes/, uploaded media 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, see LICENSE.

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%