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 Run the API locally 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_LOG_RETENTION_DAYS |
both | 30 |
The number of days that the api keeps the log of a build and a run of an operation, after the build or the run finished. The build row stays. 0 keeps all logs and runs. NixOS: logRetentionDays. |
API_DOMAIN_TERMS_URL |
both | -- | Where an operator reads the domain terms of the hosting provider. With API_DOMAIN_TERMS_VERSION, a submit or an import that registers a domain needs the acceptance of the current version. NixOS: domainTerms. |
API_DOMAIN_TERMS_VERSION |
both | -- | The current version of the domain terms at API_DOMAIN_TERMS_URL, as accepted_domain_terms of a submit gives it. NixOS: domainTerms. |
API_DOMAIN_TERMS_EFFECTIVE |
both | -- | The date from which the current version of the domain terms applies, as YYYY-MM-DD. GET /domains/terms and GET /domains show it. Unset, they show no date. NixOS: domainTerms. |
API_REGISTRY_TERMS_FILE |
both | -- | The JSON table of the terms of the registries whose extensions need an acceptance at a registration or a transfer, by extension. A submit or an import that registers a domain with such an extension needs the acceptance of these terms too. An extension in the table without documents is refused. NixOS: registryTermsFile. |
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. |
OPENBAO_ADDR |
both | -- | Address of the OpenBao server that keeps the secrets that the operator gives in the settings of an application. On a submit, api/ writes each such secret to the KV entry of the deployment and keeps only its name in secretsSet. Unset refuses a submit that gives a secret. NixOS: openbao.address. |
OPENBAO_KV_MOUNT |
both | secret |
KV version 2 mount of those secrets. NixOS: openbao.kvMount. |
OPENBAO_KV_DEPLOYMENTS |
both | vars/operator-deployments |
Path in the mount below which each deployment has its vars entries. NixOS: openbao.kvDeployments. |
TF_VAR_openbao_token |
both | -- | OpenBao token that writes those secrets, and that an operator deploy also uses. Unset refuses a submit that gives a secret. 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. |
API_SERVICE_TOKEN |
both | -- | The same token as API_SERVICE_TOKEN_FILE, as the value itself. API_SERVICE_TOKEN_FILE has precedence. The api component sets it from OpenBao through the EnvironmentFile of the service when serviceTokenSecret is set; the panel component sets that to its own generated token. |
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, that deletes the tokens of a deployment when its destroy succeeds, and that each hour deletes the tokens that no deployment uses and sets the networks of domainRegistration.zones.allowedSubnets on the others (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. |
TF_VAR_openbao_kv_mount |
full | secret |
The KV version 2 mount of the zone token at ZONE_TOKEN_KV_ADDRESS. The operator graph reads the token at the same mount, and gets this variable from api/ when it is set. NixOS: not set. |
TF_VAR_openbao_kv_prefix |
full | vars |
The path in that mount above operator-deployments/<deployment ID>, the KV subtree of the deployment. The operator graph gets this variable from api/ when it is set. NixOS: not set. |
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_CONTACT_COMMAND |
both | -- | The command that shows and applies the domain contact of an operator at the registrar account of the provider, with the verbs show and apply (registrarContact of core). It gives the /domain_contacts calls. Without it, these calls give runtime_error. The command reads the login of the state backend from REGISTRAR_CONTACT_STATE_ADDRESS and REGISTRAR_CONTACT_STATE_USERNAME. NixOS: set when the deploy credentials of the hosting provider name a registrar with this command (openprovider). |
REGISTRAR_SNAPSHOT |
both | -- | The snapshot of the registrar account that registrar-domains of core writes. 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). domain_list reads it for the status of a transfer, and the zone sweep keeps the zone of each domain that it shows in the account; when the sweep cannot read it, the sweep deletes no zone. 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. |