Architecture, README, standards, CLAUDE.md, settings reference, indexes, backlog, release plans and CHANGELOG checked against the code at v2.14.0: backfeed, notifications, counts line and web actions documented; test policy (changed area locally, full suite in CI); stale versions, statuses and links fixed; legacy and superseded docs moved. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
6.2 KiB
Development Setup
Status: Active Last Updated: 2026-11-10 (v2.14.0)
How to set up a local StarPunk environment, run the app and run the tests.
Each configuration variable is described in .env.example;
deployment is in architecture/deployment.md.
Requirements
- Python 3.14 (the container image uses
python:3.14-slim) - uv for the virtual environment and packages (ADR-006)
- git
- Optional: Docker or Podman, to build the image and run the CI test stage locally
Environment
The repository has no pyproject.toml; dependencies are in
requirements.txt (runtime) and requirements-dev.txt (adds
requirements-test.txt (pytest, pytest-mock), plus pytest-cov, black, flake8,
mypy and pip-audit).
git clone https://git.thesatelliteoflove.com/phil/StarPunk.git
cd StarPunk
uv venv --python 3.14 # creates .venv/ (gitignored)
uv pip install -r requirements-dev.txt
Run everything through uv run, which picks up .venv/ automatically:
uv run pytest, uv run flask ..., uv run python .... Never install into
the system Python.
To add a dependency, add a pinned line (package==X.Y.*) with a short
comment to requirements.txt, then uv pip install -r requirements.txt.
The file is maintained by hand; don't overwrite it with pip freeze.
Configuration
cp .env.example .env
python3 -c "import secrets; print(secrets.token_hex(32))" # paste as SESSION_SECRET
starpunk/config.py loads .env (python-dotenv; real environment
variables win) and validates at startup, raising ValueError with every
problem it found. What is required depends on the mode:
| Setting | Production | DEV_MODE=true |
|---|---|---|
SESSION_SECRET |
required | required |
SITE_URL, SITE_NAME, SITE_AUTHOR |
required (have defaults) | same |
ADMIN_ME |
required | optional |
OIDC_ISSUER, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET, OIDC_ADMIN_SUB |
required | optional |
DEV_ADMIN_ME |
unused | required |
TOKEN_ENDPOINT and INDIELOGIN_URL are no longer read (v2.0.0 replaced
IndieLogin with OIDC admin login and a built-in IndieAuth server, ADR-064);
the app logs a warning if they are set.
Running the app locally
There is no separate database step: create_app() creates DATA_PATH,
NOTES_PATH and the database, and applies pending migrations
(starpunk/migrations.py) at startup.
For local work, use development login instead of OIDC (ADR-011):
# in .env
DEV_MODE=true
DEV_ADMIN_ME=http://localhost:5000/
uv run flask --app app.py run --debug # http://localhost:5000
DEV_MODE=true registers /dev/login (otherwise those routes don't exist),
adds a "Quick Dev Login (No Auth)" button to /auth/login and a warning
banner to every page. It sets the starpunk_session cookie for
DEV_ADMIN_ME without any authentication: never enable it on a reachable
server.
Each app process also starts background threads: the webmention worker,
the WebSub hub worker and, when a crossposting target is configured, the
syndication worker. Turn off what you don't need locally with
WEBMENTION_WORKER_ENABLED=false and WEBSUB_ENABLED=false. Leave GOTOSOCIAL_*, BLUESKY_* and THREADS_*
empty unless you mean to post to those accounts.
Production runs the same app under gunicorn (gunicorn app:app, see CMD
in Containerfile). To try the image locally:
docker build -t starpunk:dev -f Containerfile .
docker run --rm -p 8000:8000 --env-file .env -v ./container-data:/data starpunk:dev
Running the tests
SESSION_SECRET=test uv run pytest tests/test_websub.py # the area you changed
SESSION_SECRET=test uv run pytest tests/test_micropub.py -k delete -x
SESSION_SECRET=test uv run pytest # full suite (CI runs this; rarely needed locally)
SESSION_SECRETmust be set (in.envor the environment) becauseload_config()checks it before the test overrides are applied. The CI test stage also setsSITE_URL=http://localhost:5000andADMIN_ME=https://test.example.com; set them too to reproduce CI exactly.tests/conftest.pybuilds each app withTESTING=Trueand a temporaryDATA_PATHand database, so tests never touch./data. UnderTESTING=Truethe background workers don't start and the production OIDC check is skipped.- Locally, run the tests for the area you changed; the full suite, including
the slow
tests/test_migration_race_condition.py(about 5 minutes), runs in CI on the release tag. - Coverage:
SESSION_SECRET=test uv run pytest --cov=starpunk --cov-report=term-missing. - The CI test stage can be reproduced exactly with
docker build --target test -f Containerfile .(see testing-checklist.md).
Useful commands
# Version
uv run python -c "import starpunk; print(starpunk.__version__)"
# Inspect the database
sqlite3 data/starpunk.db '.tables'
sqlite3 data/starpunk.db 'SELECT migration_name, applied_at FROM schema_migrations ORDER BY id'
# Reset local data (deletes notes, media and the database)
rm -rf data/
Troubleshooting
| Symptom | Cause |
|---|---|
SESSION_SECRET must be set in .env file (also from pytest) |
SESSION_SECRET missing from .env and the environment |
Production mode requires OIDC_ISSUER to be set |
DEV_MODE is not true and OIDC is not configured |
DEV_MODE=true requires DEV_ADMIN_ME to be set |
set DEV_ADMIN_ME |
ModuleNotFoundError |
run through uv run after uv pip install -r requirements-dev.txt |
/dev/login returns 404 |
DEV_MODE is not true |