Files
StarPunk/README.md
T
PhilandClaude Opus 5.5 742e2e3ec3 Remove the metrics dashboard and monitoring package (v2.12.0)
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>
2026-11-03 16:07:47 -07:00

118 lines
5.2 KiB
Markdown

# 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/health` diagnostics, 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 `<SITE_URL>/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
[MIT](LICENSE): use, change and share it for anything, including
commercially, as long as the copyright and license notice stay with it.