Files
StarPunk/docs/standards/development-setup.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

6.1 KiB

Development Setup

Status: Active Last Updated: 2026-11-03 (v2.10.1)

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 pytest-cov, pytest-mock, black, flake8, mypy).

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                          # full suite
SESSION_SECRET=test uv run pytest tests/test_websub.py      # one file
SESSION_SECRET=test uv run pytest tests/test_micropub.py -k delete -x
  • SESSION_SECRET must be set (in .env or the environment) because load_config() checks it before the test overrides are applied. The CI test stage also sets SITE_URL=http://localhost:5000 and ADMIN_ME=https://test.example.com; set them too to reproduce CI exactly.
  • tests/conftest.py builds each app with TESTING=True and a temporary DATA_PATH and database, so tests never touch ./data. Under TESTING=True the background workers don't start and the production OIDC check is skipped.
  • tests/test_migration_race_condition.py is slow (about 5 minutes). While iterating, add --ignore=tests/test_migration_race_condition.py; run the full suite before releasing.
  • 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

References