Files
StarPunk/docs/standards/development-setup.md
T
PhilandClaude Opus 5.5 75946be7b2 maint: Dependency upgrades and High backlog items (v2.11.0)
- All dependencies to current releases (97 known vulnerabilities -> 0),
  Python 3.14, uv pinned, requirements-test.txt, lxml/dateutil pinned
- CSRF tokens on admin forms, logout and IndieAuth consent
- IndieAuth client and crosspost link-card fetches via safe_get
- FLASK_DEBUG/FLASK_ENV default off/production; image sets them
- Foreign keys enforced on pooled connections; migration 018 removes orphans
- Rate limits shared across processes (rate_limits, migration 019)
- datetime.utcnow() and sqlite3 default adapters replaced
- compose.yaml fixed; duplicate dev_auth.py and test.ini removed

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-03 13:09:52 -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, the memory monitor and, when a crossposting target is configured, the syndication worker. Turn off what you don't need locally with WEBMENTION_WORKER_ENABLED=false, WEBSUB_ENABLED=false and METRICS_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 and memory monitor 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