Files
StarPunk/docs/standards/development-setup.md
T
PhilandClaude Opus 5.5 ceef048003 docs: documentation review for v2.14.0
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>
2026-11-10 14:51:57 -07:00

155 lines
6.2 KiB
Markdown

# 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`](../../.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
`requirements-test.txt` (pytest, pytest-mock), plus pytest-cov, black, flake8,
mypy and pip-audit).
```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 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_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.
- 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](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)