# 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`](starpunk/__init__.py); what changed in each release is in [CHANGELOG.md](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](https://www.w3.org/TR/micropub/): create, update, delete and undelete; media endpoint; `q=config`, `source`, `syndicate-to`, `category` - Built-in [IndieAuth](https://indieauth.spec.indieweb.org/) server for Micropub apps (consent screen, tokens, revocation, Connected Apps page) - Admin login through any OpenID Connect provider (e.g. Pocket ID) - [Webmention](https://www.w3.org/TR/webmention/): receiving (verified, moderated, rate-limited) and sending; replies, likes and reposts shown on each note - [WebSub](https://www.w3.org/TR/websub/) with a built-in hub, so readers get new posts within seconds - [Microformats2](https://microformats.org/wiki/h-entry): 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 ```bash 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 `/auth/callback` as the redirect URI with your OIDC provider. Details: [docs/architecture/deployment.md](docs/architecture/deployment.md). ### Local development ```bash 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](docs/standards/development-setup.md). ## Configuration All settings are environment variables (or a `.env` file), each listed with its default in [`.env.example`](.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](docs/DOCUMENTATION.md) | | System overview | [docs/architecture/overview.md](docs/architecture/overview.md) | | Technology stack | [docs/architecture/technology-stack.md](docs/architecture/technology-stack.md) | | Database and migrations | [docs/architecture/database.md](docs/architecture/database.md) | | Deployment | [docs/architecture/deployment.md](docs/architecture/deployment.md) | | Authentication (OIDC, IndieAuth) | [docs/architecture/simplified-auth-architecture.md](docs/architecture/simplified-auth-architecture.md) | | IndieWeb protocols | [docs/architecture/indieweb-protocols.md](docs/architecture/indieweb-protocols.md) | | Feeds and crossposting | [docs/architecture/syndication-architecture.md](docs/architecture/syndication-architecture.md) | | Decisions (ADRs) | [docs/decisions/INDEX.md](docs/decisions/INDEX.md) | | Per-release designs and reports | [docs/design/](docs/design/) | | Backlog | [docs/projectplan/BACKLOG.md](docs/projectplan/BACKLOG.md) | | Development standards and release process | [docs/standards/INDEX.md](docs/standards/INDEX.md) | ## License [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/): use, share and adapt it for anything, including commercially, as long as you credit the author (Phil Skentelbery, with a link to the project). See [LICENSE](LICENSE).