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_AUDIT_RETENTION_DAYS |
both | 365 |
The number of days that the audit_event table keeps an event. 0 keeps all events. NixOS: auditRetentionDays. |
API_STATE_DB |
both | /var/lib/fediversity-api/state.db |
Path of the SQLite deployment state DB, used when API_DATABASE_URL is unset. With API_DATABASE_URL set, api/ copies this file into PostgreSQL once on start while the PostgreSQL tables are empty. NixOS: under the service's StateDirectory. |
API_DATABASE_URL |
both | -- | PostgreSQL connection string (postgresql://...) of the deployment state DB. Unset uses the SQLite file at API_STATE_DB. NixOS: the hosting provider's central database, from the component's api-db request. |
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. Unset in api-http-stack: it writes one from the DEPLOYMENT_* variables. |
DEPLOYMENT_ROOT |
both | -- | api-http-stack without DEPLOY_CONFIG_FILE: the flake of the deployment program. NixOS: deployment.root_path. |
DEPLOYMENT_ATTRIBUTE |
both | -- | api-http-stack without DEPLOY_CONFIG_FILE: the dev shell of the deployment program. NixOS: deployment.attribute. |
DEPLOYMENT_STATE_ADDRESS_VARS |
both | {} |
api-http-stack without DEPLOY_CONFIG_FILE: JSON map of Terraform variables to the suffix of the state address of an other deploy. NixOS: deployment.stateAddressVars. |
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. api-http-stack writes it into its deploy config when it starts; 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://127.0.0.1:8000/api/authz/ in api-http-stack |
HTTP endpoint called per request for dynamic authorization; empty refuses to start, unless API_AUTHZ_ALLOW_ALL is set. NixOS: authz.callbackUrl. |
API_AUTHZ_ALLOW_ALL |
both | -- | Allow every request without AUTHZ_CALLBACK_URL (development and tests only). In api-http-stack, it also stops the defaults of AUTHZ_CALLBACK_URL and AUTHZ_CALLBACK_TOKEN_FILE. NixOS: authz.allowAll. |
API_SERVICE_TOKEN_FILE |
both | -- | Path to a file containing the static token of internal calls. A request with that bearer goes to the authz callback with internal: true and without the token. NixOS: authz.serviceTokenFile. |
AUTHZ_CALLBACK_TOKEN_FILE |
both | $XDG_RUNTIME_DIR/fediversity-authz/token in api-http-stack |
Path to a file containing a static token that api/ sends to the authz callback as Authorization: Bearer <token>, so that the callback can refuse requests that do not come from api/; empty sends no token. NixOS: authz.callbackTokenFile. |
AUTHZ_CALLBACK_TOKEN |
both | -- | The same token as AUTHZ_CALLBACK_TOKEN_FILE, as the value itself. AUTHZ_CALLBACK_TOKEN_FILE has precedence. The api component sets it from OpenBao through the EnvironmentFile of the service when authzCallbackTokenSecret is set; the panel component sets that to its own generated token. |
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. |
ZONES_MANAGER_TOKEN |
full | -- | The deSEC token that makes the zone of a registered domain and a token that can write only that zone, before a deploy starts, and that deletes the tokens of a deployment when its destroy succeeds (fediversity_api.zone_tokens). Only when the curation holds zones at deSEC (domainRegistration.zones). It stays in this process: the deploy gets only the scoped token. NixOS: the OpenBao broker's EnvironmentFile. |
ZONE_FOLLOW_PROBE_LABELS |
both | -- | Comma-separated labels below a followed deSEC zone that the follow also asks the new nameservers for when it copies the zone by queries (fediversity_api.zone_follow): when no new nameserver gives a zone transfer or an NSEC walk. The copy then also has such a name that only the target holds. NixOS: zoneFollow.probeLabels, by default the labels under which Fediversity writes records. |
ZONE_FOLLOW_WHOAMI_URLS |
both | -- | Comma-separated HTTPS URLs that give the address of the client, as plain text or as JSON with data.ip. When the route of api to other networks for an IP version has a local address that is not global, for example behind NAT, an export with a deSEC zone to follow asks these URLs in order for the global address of that IP version, for the transfer_sources of the migration string (fediversity_api.migration). Empty asks no URL. NixOS: zoneFollow.whoamiUrls. |
ZONE_TOKEN_KV_ADDRESS |
full | -- | The OpenBao address where the scoped zone token goes, under the KV subtree of the deployment. NixOS: services.vars-openbao.address. |
ZONE_TOKEN_KV_CACERT_FILE |
full | the system CAs | The CA that the OpenBao certificate at ZONE_TOKEN_KV_ADDRESS is verified against. NixOS: services.vars-openbao.caCertFile. |
OPENPROVIDER_USERNAME |
both | -- | The login name of the registrar account that the operator deploys use. REGISTRAR_COMMAND gets it from the environment of the api. NixOS: the deploy credentials of the hosting provider, when the served curation registers a domain. |
OPENPROVIDER_PASSWORD |
both | -- | The password of the registrar account of OPENPROVIDER_USERNAME. NixOS: as OPENPROVIDER_USERNAME. |
OPENPROVIDER_BASE_URL |
both | https://api.openprovider.eu |
The registrar API of OPENPROVIDER_USERNAME. The operator deploys and REGISTRAR_COMMAND get the same value. NixOS: operatorRegistrar.baseUrl of the api component. |
REGISTRAR_COMMAND |
both | -- | The command that reads and changes the transfer state of a domain at the registrar account of the provider, with the verbs holds, release and retake (registrarTransfer of core). With it, the api releases the domain of a migration export, and locks it again on a resume. Without it, the api makes no call to the registrar. The command gets the environment of the api, thus also the login of the account. NixOS: registrar-transfer of core, when the deploy credentials of the hosting provider have the OPENPROVIDER_ login. |
REGISTRAR_SNAPSHOT |
both | -- | The snapshot of the registrar account that registrar-domains of core writes. Only fediversity-api-domain-renewals reads it: when the expiry of a domain moves forward, it records a renewal at the renewal price of the snapshot, and when a domain leaves the account, it records a release (see GET /usage). NixOS: registrarSnapshot, which also starts the command at each change of the snapshot. |
SSH_AUTH_SOCK |
both | -- | SSH agent socket, given to each deploy subprocess. Use it for a password-protected SSH key; see api/README.md. |
XDG_RUNTIME_DIR |
both | /tmp |
api-http-stack, windmill-dev and centrifugo-dev keep their run-time state (the state DB, the Windmill token, the Centrifugo key) under $XDG_RUNTIME_DIR/fediversity-<name>/. api-http-stack and the panel devShell share the authz callback token in $XDG_RUNTIME_DIR/fediversity-authz/token. |
XDG_STATE_HOME |
both | ~/.local/state |
terraform-backend-dev keeps the Terraform state under $XDG_STATE_HOME/fediversity/tf-backend. api-http-stack reads the TF_VAR_* values that dev-tf-incus-bootstrap writes to $XDG_STATE_HOME/fediversity/tf-env. |
XDG_CACHE_HOME |
both | the temporary directory | Cache of the git fetches that check API_TRUSTED_SOURCE_URLS, and of the git fetcher of Nix. NixOS: /var/cache/fediversity-api. |
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
endpoints a docs reader can call without a token, such as GET /schema, are
public anyway. A docs reader with a token of the front-end calls as the user of
that token, as the front-end could. 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, from the eventsHost argument. Unset renders the bare {host} placeholder. |
DNS_DOMAIN |
core/apex.nix |
The deployment's apex, from which swagger-ui derives the api/ host it advertises. Unset, the evaluation stops: core has no fallback apex. openapi and openapi-validate name no deployed server and do not read it. |