Files
StarPunk/docs/standards/development-setup.md
T
PhilandClaude Opus 5.5 0716984958 docs: Bring all documentation up to date for v2.10.1
- architecture/: overview, technology stack, auth (OIDC + built-in
  IndieAuth), syndication (POSSE) rewritten; new database.md,
  deployment.md and indieweb-protocols.md; legacy stack marked historical
- decisions/: reconstructed ADR-060 and ADR-063; 31 status corrections
  (superseded auth ADRs, proposed -> accepted); INDEX rebuilt
- design/: reconstructed the v1.6.0 documents the webmention code cites;
  reports for 18 v2 releases without a design folder; INDEX rebuilt
- projectplan/: BACKLOG rewritten (shipped items removed, open issues from
  the reviews added); RELEASE.md for v2.0.0-v2.10.1; INDEX
- standards/: development setup (uv, tests, DEV_MODE), testing (CI test
  stage), git and release flow, versioning, coding standards, cookies
- README, CLAUDE.md, .env.example (every setting the code reads, with
  defaults) brought up to date
- 137 broken links repaired (old absolute paths, moved files); stale ADR
  references in code comments corrected (comments only)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-03 12:40:19 -07:00

155 lines
6.1 KiB
Markdown

# 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.11 (the container image uses `python:3.11-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.11 # 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, 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:
```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 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](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)