Local setup¶

Docker Compose (recommended)¶

Same as Install. Use Caddyfile.dev for self-signed TLS if needed.

Python host (partial)¶

python3 -m venv .venv
source .venv/bin/activate
# Locked deps (same as Docker/CI) — do not use floating pip install -e ".[dev]" for release work
pip install --require-hashes -r requirements.lock.txt
pip install --no-deps -e .
# Or: uv sync --frozen --extra dev
# Refresh pins: ./scripts/refresh-lockfiles.sh
# Need Postgres + Redis (compose up db redis) and .env
uvicorn app.main:app --reload

Schema: Alembic on startup, or:

alembic upgrade head

Frontend assets¶

Tailwind is compiled CSS (app/static/css/tailwind.css, committed). After adding new utility classes in templates or app/static/js:

bash scripts/build-tailwind.sh   # needs npx or Docker

HTMX / Alpine / xterm are vendored at image build:

bash scripts/vendor_cdns.sh
# or VENDOR_INSECURE=1 if TLS intercept issues

Dependency locks¶

File	Role
`pyproject.toml`	Declared mins
`uv.lock`	Resolver source of truth
`requirements.lock.txt`	Hashed pins for Docker + CI (runtime + dev)
`requirements.runtime.lock.txt`	Runtime-only pins

./scripts/refresh-lockfiles.sh   # after changing pyproject deps (needs uv)

See SECURITY.md (Dependencies & supply chain).

Docs site (this wiki)¶

pip install -r requirements-docs.txt
mkdocs serve
# open http://127.0.0.1:8000

See Contributing docs.