[NathanCummings]

Following the README's steps for running FDS from a checkout (docker compose up -d postgres, uv run alembic upgrade head, uvicorn ... --reload) and then seeding with a minted token fails with:

httpx.HTTPStatusError: Client error '401 Unauthorized' for url 'http://localhost:8000/v1/devices/'

Those steps set only FDS_DB_PASSWORD. FDS_TRUSTED_IDPS defaults to empty, so FDS trusts no issuer and the response body says Untrusted Issuer: urn:fds:local. With the issuer set but not FDS_OIDC_AUDIENCE, it becomes Audience doesn't match. The alembic upgrade head step before it also fails, with fe_sendauth: no password supplied, because the password is only given to uvicorn. The compose stack is not affected: it sets both, and seeding a fresh stack from main works.

Changes

• .env.example trusts the key pair from scripts/mint-token.py alongside the development Keycloak realm, as compose.yaml does, and sets the development database's password. Its header no longer mentions SQLite or demo/docker-compose.yaml, neither of which exists any more.

• README: to run from a checkout, copy .env.example to .env, which FDS and alembic both read. It also says that without those settings every token is refused with a 401.

• README and docs/operations.md: both said .env.example lists each setting with its default. It hasn't for a while (the audience and issuer list differ from the defaults), so they now say what it holds.

• scripts/seed-example-catalogue.py: an HTTP error now exits with the method, URL, status and FDS's response body instead of a traceback. For the case above that reads POST http://localhost:8000/v1/devices/ returned 401: {"detail":"Untrusted Issuer: urn:fds:local"}.

• .env.example also configured an S3 store at localhost:9000 whose credentials came from minio:9000, a container hostname, though the development stack runs no object store. It now configures none, as compose.yaml doesn't, and keeps the S3 entry as an example beside the GCS and Azure ones.

• README and CONTRIBUTING pointed the tests at the stack's fds database. The tests create records the example catalogue already holds (device mast, for one), so once the stack is seeded, 90 fail and 131 error. They now use fds_test, created once on the same server, as CI does.

.env.example now holds working development values rather than defaults. That matches what its header already said it was for, and the README is the only place that tells you to copy it.

Checked

• New README steps from scratch (fresh Postgres volume, new key pair, cp .env.example .env, alembic, uvicorn, seed): migrations apply and the seed completes.
• Same, without .env: the seed script exits 1 with the message above.
• uv run --all-extras pytest with that .env in the checkout: 880 passed.
• With the empty provider list: the seed completes.
• Tests against the seeded stack's fds database: 659 passed, 90 failed, 131 errors. Against fds_test, created with the documented command on the same server: 880 passed.
• prek hooks and zensical build --strict pass.

🤖 Generated with Claude Code