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>
155 lines
6.2 KiB
Markdown
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)
|