Files
StarPunk/docs/architecture/technology-stack.md
T
2026-11-10 14:30:01 -07:00

6.1 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.14 (python:3.14-slim base image; since v2.11.0)
Web framework Flask 3.1 (Werkzeug, Jinja2, itsdangerous, click come with it)
WSGI server gunicorn 26.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)

Pinned to a minor series. Upgraded in v2.11.0, when the set had no known vulnerabilities (pip-audit); check again before each release.

Package Pin Used for
Flask 3.1.* Web framework
gunicorn 26.2.* Production WSGI server
markdown 3.11.* Rendering notes (extra, codehilite, nl2br and a bare-URL linking extension)
nh3 0.3.* HTML sanitising (rendered notes, webmention content)
beautifulsoup4 4.15.* HTML parsing: IndieAuth client pages, crosspost text and link cards
lxml 6.1.* Outgoing link extraction, webmention endpoint discovery and source checks
mf2py 2.0.* Parsing microformats2 (webmention sources, reply contexts, author h-card)
python-dateutil 4.0.* Dates in reply contexts
feedgen 1.0.* RSS 2.0 feed (starpunk/feeds/rss.py); Atom and JSON Feed are generated by StarPunk's own code
httpx 0.28.* All outbound HTTP; requests to user-supplied URLs go through webmention_ssrf.safe_get/safe_post
apprise 2.2.* Notifications to the owner's services (starpunk/notifications.py, ADR-074); sends to the URLs the owner configures, outside the SSRF-safe fetcher
PyJWT[crypto] 2.15.* Verifying OIDC ID tokens (JWKS, RS/ES signatures via cryptography)
python-dotenv 1.2.* Loading .env
Pillow 13.0.* Image validation, resizing and variants
pillow-heif 1.8.* HEIC/HEIF uploads (iPhone photos)

markupsafe comes with Flask/Jinja2.

Test and development dependencies

  • requirements-test.txt: pytest 9.2 and pytest-mock 3.15, used by the Containerfile test stage (CI).
  • requirements-dev.txt: runtime and test requirements plus pytest-cov, black, flake8, mypy (not enforced) and pip-audit. 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_*.py per module or feature, shared fixtures in tests/conftest.py, helpers in tests/helpers/).

  • Isolation: the app fixture calls create_app() with TESTING=True and a temporary data directory, so every test gets a fresh database (all migrations applied) and note directory. With TESTING=True no background threads start and the OIDC settings are not required; tests drive worker functions directly.

  • Network: outbound HTTP is mocked; webmention_ssrf.TRANSPORT accepts an httpx.MockTransport for fetcher tests.

  • Running locally:

    uv venv && uv pip install -r requirements-dev.txt
    .venv/bin/python -m pytest
    
  • In CI: the test stage of the Containerfile installs the production requirements plus requirements-test.txt 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)