- architecture/: overview, technology stack, auth (OIDC + built-in IndieAuth), syndication (POSSE) rewritten; new database.md, deployment.md and indieweb-protocols.md; legacy stack marked historical - decisions/: reconstructed ADR-060 and ADR-063; 31 status corrections (superseded auth ADRs, proposed -> accepted); INDEX rebuilt - design/: reconstructed the v1.6.0 documents the webmention code cites; reports for 18 v2 releases without a design folder; INDEX rebuilt - projectplan/: BACKLOG rewritten (shipped items removed, open issues from the reviews added); RELEASE.md for v2.0.0-v2.10.1; INDEX - standards/: development setup (uv, tests, DEV_MODE), testing (CI test stage), git and release flow, versioning, coding standards, cookies - README, CLAUDE.md, .env.example (every setting the code reads, with defaults) brought up to date - 137 broken links repaired (old absolute paths, moved files); stale ADR references in code comments corrected (comments only) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
5.9 KiB
StarPunk Technology Stack
Version: 2.10.1 (2026-11-03) Status: Current. The original v0.x stack write-up is kept as technology-stack-legacy.md for history.
StarPunk deliberately uses few dependencies: a WSGI web framework, SQLite from the standard library, plain files, server-rendered templates and a handful of libraries for parsing, images and security. No JavaScript build, no external database, no task queue. See overview.md for how the pieces fit together.
Runtime
| Component | Choice |
|---|---|
| Language | Python 3.11 (python:3.11-slim base image) |
| Web framework | Flask 3.0 (Werkzeug, Jinja2, itsdangerous, click come with it) |
| WSGI server | gunicorn 21.2, 4 sync workers (see deployment.md) |
| Database | SQLite (standard-library sqlite3), WAL mode, FTS5 for search |
| Content storage | Markdown files on disk |
| Background work | threading daemon threads; fcntl.flock file locks to pick one process |
| Templates | Jinja2, server-side rendered |
| Front end | One hand-written stylesheet; one small vanilla JS file for the editor's Markdown preview |
| Packaging | uv creates the virtual environment and installs requirements (locally and in the image) |
| Container | Multi-stage Containerfile (Podman/Docker), non-root user |
| Reverse proxy | Caddy in production (examples for Caddy and nginx in the repo) |
Python dependencies (requirements.txt)
| Package | Pin | Used for |
|---|---|---|
| Flask | 3.0.* |
Web framework |
| gunicorn | 21.2.* |
Production WSGI server |
| markdown | 3.5.* |
Rendering notes (extra, codehilite, nl2br and a bare-URL linking extension) |
| feedgen | 1.0.* |
RSS 2.0 feed (starpunk/feeds/rss.py); Atom and JSON Feed are generated by StarPunk's own code |
| httpx | 0.27.* |
All outbound HTTP: OIDC, IndieAuth client discovery, webmention and WebSub requests (through the SSRF-safe wrapper in webmention_ssrf.py), crossposting APIs, health check |
| python-dotenv | 1.0.* |
Loading .env |
| beautifulsoup4 | 4.12.* |
HTML parsing: IndieAuth client pages, crosspost text and link cards |
| mf2py | 2.0.* |
Parsing microformats2 (webmention sources, reply contexts, author h-card) |
| pytest | 8.0.* |
Test runner (listed here as well as in the image's test stage) |
| psutil | 5.9.* |
Memory monitor and system metrics |
| Pillow | 10.1.* |
Image validation, resizing and variants |
| pillow-heif | 0.18.* |
HEIC/HEIF uploads (iPhone photos) |
| nh3 | 0.2.* |
HTML sanitising (rendered notes, webmention content) |
| PyJWT[crypto] | 2.10.* |
Verifying OIDC ID tokens (JWKS, RS/ES signatures via cryptography) |
Packages imported directly but installed only as dependencies of the above:
lxml (outgoing link extraction, webmention endpoint discovery and source checks; from feedgen) and python-dateutil (dates in
reply contexts; from feedgen). markupsafe comes with Flask/Jinja2.
Development dependencies (requirements-dev.txt)
Includes requirements.txt, plus pytest-cov, pytest-mock, black,
flake8, mypy and gunicorn. Coding standards are in
../standards/.
Deliberately not used
No ORM (plain SQL), no Flask extensions (login, WTF, SQLAlchemy, caching), no Celery/Redis or other broker (worker threads with SQLite queues), no front-end framework or bundler, no separate search server.
Standards implemented
| Area | Standards |
|---|---|
| IndieWeb | Micropub (create, update, delete, undelete, queries, media endpoint), IndieAuth (authorization server with PKCE, metadata endpoint, token revocation), Webmention (send and receive), WebSub (publisher and built-in hub), microformats2 (h-entry, h-feed, h-card markup and parsing), rel=me |
| Login | OpenID Connect authorization code flow with PKCE (provider: Pocket ID) |
| Feeds | RSS 2.0, Atom 1.0, JSON Feed 1.1, OPML 2.0, HTTP content negotiation |
| Crossposting | Mastodon client API (GoToSocial), AT Protocol (Bluesky XRPC), Threads Graph API |
Protocol details: indieweb-protocols.md, simplified-auth-architecture.md, syndication-architecture.md.
Testing
-
Framework: pytest with pytest-mock; about 1,250 tests in
tests/(test_*.pyper module or feature, shared fixtures intests/conftest.py, helpers intests/helpers/). -
Isolation: the
appfixture callscreate_app()withTESTING=Trueand a temporary data directory, so every test gets a fresh database (all migrations applied) and note directory. WithTESTING=Trueno background threads start and the OIDC settings are not required; tests drive worker functions directly. -
Network: outbound HTTP is mocked;
webmention_ssrf.TRANSPORTaccepts anhttpx.MockTransportfor fetcher tests. -
Running locally:
uv venv && uv pip install -r requirements-dev.txt .venv/bin/python -m pytest -
In CI: the
teststage of theContainerfileinstalls the production requirements plus pytest and pytest-mock and runs the whole suite. The image is only built and pushed if it passes. Checklist: ../standards/testing-checklist.md.
CI/CD
Gitea Actions, one workflow (.gitea/workflows/build-container.yml), run on
vX.Y.Z tags or by hand: build the test stage (runs pytest), then build
and push the runtime image to the Gitea container registry tagged with the
version and latest. Builds go to a rootless BuildKit daemon; there is no
Docker daemon on the runner. Production pulls the new tag through the
Ansible-managed deployment. Details: deployment.md.
Versioning
Semantic versioning; the version is __version__ in starpunk/__init__.py
and every release has a CHANGELOG.md entry and a vX.Y.Z git tag. See
../standards/ for the versioning and git-branching
standards.
Last Updated: 2026-11-03 (v2.10.1)