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>
118 lines
5.2 KiB
Markdown
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.
|