The in-memory metrics system covered one gunicorn process at a time, was lost on restart and was never used. Remove /admin/metrics-dashboard, /admin/metrics, starpunk/monitoring, the HTTP/query timing, memory monitor, feed counters, METRICS_* settings and psutil. Keep /health, /admin/health (without its metrics block), pool stats and the feed cache. ADR-072. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
5.2 KiB
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-syndicationlinks back; edits and deletes follow, native likes and boosts where the target supports them
Operations
- Migrations applied automatically at startup
/healthendpoint,/admin/healthdiagnostics, 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: use, change and share it for anything, including commercially, as long as the copyright and license notice stay with it.