Environment reference
Every knob api/ reads from its process environment. This is the reference for
running api/ by hand -- from the dev shell, or as a standalone service. On NixOS
you do not set these directly: the
services.fediversity-api options derive them, and
where a row below shadows one, the option is named in its description. The
serving process parses them once, at startup, into fediversity_api.settings;
its docstring pairs each variable with the field a module reads it from.
Variables marked full are only used in the full local-dev setup (Windmill
plus Centrifugo); leave them unset for the simple synchronous setup. See
api/README.md
for how to bring either of those up.
| Variable | Setup | Default | Description |
|---|---|---|---|
API_HTTP_LISTEN_ADDR |
both | 127.0.0.1 |
Bind address for the HTTP server. NixOS: http.listenAddr. |
API_HTTP_LISTEN_PORT |
both | 8088 |
Bind port for the HTTP server. NixOS: http.listenPort. |
API_STATE_DB |
both | /var/lib/fediversity-api/state.db |
Path of the SQLite deployment state DB. NixOS: under the service's StateDirectory. |
API_RESET_STATE |
both | -- | When set, api-http-stack wipes the deployment state DB on start; unset persists it across restarts. |
API_CORS_ORIGINS |
both | -- | Comma-separated browser origins allowed to call api/ directly; empty disables CORS. Doubles as the destroy-reconcile callback allowlist. NixOS: frontendOrigins. |
API_DOCS_ORIGINS |
both | -- | Comma-separated extra browser origins allowed to call api/ via CORS without becoming callback targets. NixOS: docsOrigins. |
API_SERVERS |
both | -- | JSON list of OpenAPI server objects to publish as the spec's servers, which is what Swagger UI's host dropdown offers. Unset omits the key entirely. NixOS: derived from domain. |
API_TRUSTED_SOURCE_URLS |
both | -- | Comma-separated exact module_source repo URLs api/ will fetch and deploy. An explicit empty value allows any source. NixOS: trustedSourceUrls. |
DEPLOY_CONFIG_FILE |
both | -- | Path to deploy-config.json. |
TF_HTTP_ADDRESS |
both | http://127.0.0.1:8888/state/local/default |
Terraform HTTP backend URL, which api/ scopes per deployment namespace. The default is api-http-stack's; the service reads no default, and unset skips the scoping. |
TERRAFORM_BACKEND_ADDR |
both | 127.0.0.1:8888 |
Bind address for terraform-backend-dev. |
WINDMILL_BASE_URL |
full | -- | Windmill instance URL, baked into api-http-stack's deploy config; empty disables Windmill (uses the subprocess fallback). |
WINDMILL_TOKEN |
full | -- | Windmill API token, sent as a bearer; empty sends no Authorization header. NixOS: the OpenBao broker's EnvironmentFile. |
CENTRIFUGO_API_URL |
full | -- | Centrifugo HTTP API base URL; empty disables event publishing. NixOS: centrifugo.apiUrl. |
CENTRIFUGO_API_KEY_FILE |
full | -- | Path to a file containing the Centrifugo HTTP admin key. NixOS: centrifugo.apiKeyFile. |
CENTRIFUGO_API_KEY |
full | -- | The Centrifugo HTTP admin key itself, read only when CENTRIFUGO_API_KEY_FILE is unset. |
AUTHZ_CALLBACK_URL |
both | -- | HTTP endpoint called per request for dynamic authorization; empty allows every request (dev only). NixOS: authz.callbackUrl. |
SELF_MODULE_SOURCE |
both | -- | JSON fetchTree pin of api/'s own revision; freezes the default-source schema baseline. NixOS: deployment.selfModuleSource. |
PIN_EFFECT |
both | -- | Build-time (--impure): collapse the schema to a single deployment method / effect, dropping the picker. NixOS: pinEffect. |
HOSTING_CONFIG |
both | -- | Build-time (--impure): path to the hosting provider's curated-form file; its fixed leaves are pruned from the schema and baked at deploy. See hosting resources. |
API_CORS_ORIGINS and API_DOCS_ORIGINS are not interchangeable
API_CORS_ORIGINS names the front-ends, and is trusted in both directions: an
origin on it may call api/ from a browser, and is a legal target for the
destroy-reconcile callback api/ POSTs to ask whether a request is authorized.
API_DOCS_ORIGINS widens the browser half only. It exists so the published
Swagger UI bundle's "Try it out" button can reach a deployed api/ without that
static pages host becoming an authorization oracle. That is safe because
credentialed CORS is off (a browser attaches no ambient cookies), api/ does no
bearer validation of its own and answers a tokenless call with 403, and the one
endpoint a docs reader can exercise without a token -- GET /schema -- is
unauthenticated anyway. CORS restricts browsers only; anyone holding a token
could always call from outside one.
Build-time only
Two further variables are read when generating artifacts rather than when
serving, so they belong to the derivations in api/nix/ and never to a running
service:
| Variable | Read by | Description |
|---|---|---|
API_EVENTS_HOST |
api/nix/asyncapi.nix |
Default for the AsyncAPI host server variable. Unset renders the bare {host} placeholder. |
DNS_DOMAIN |
core/apex.nix |
The deployment's apex, from which the generated specs derive the api/ and Centrifugo hostnames they advertise. Under a pure evaluation it is unset and the apex falls back to abundos.eu. |