# 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`](../../.env.example); deployment is in [architecture/deployment.md](../architecture/deployment.md). ## Requirements - Python 3.14 (the container image uses `python:3.14-slim`) - [uv](https://docs.astral.sh/uv/) for the virtual environment and packages ([ADR-006](../decisions/ADR-006-python-virtual-environment-uv.md)) - 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). ```bash 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 ```bash 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](../decisions/ADR-011-development-authentication-mechanism.md)): ```bash # in .env DEV_MODE=true DEV_ADMIN_ME=http://localhost:5000/ ``` ```bash 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: ```bash 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 ```bash 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](testing-checklist.md)). ## Useful commands ```bash # 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 - [ADR-006: Python virtual environment with uv](../decisions/ADR-006-python-virtual-environment-uv.md) - [ADR-011: Development authentication](../decisions/ADR-011-development-authentication-mechanism.md) - [ADR-064: OIDC admin login and built-in IndieAuth server](../decisions/ADR-064-oidc-admin-login-and-builtin-indieauth-server.md) - [python-coding-standards.md](python-coding-standards.md), [testing-checklist.md](testing-checklist.md), [git-branching-strategy.md](git-branching-strategy.md)