Settings reference · Install and configure

Generated by apelora-control-plane settings (npm run settings:doc) from the list the control plane itself reports at GET /api/v1/settings. Do not edit by hand.

Every setting is an environment variable. The control plane reads its own at start; the worker reads its own; a setting both read must be given to both. A value marked never shown (a secret, or the path of a certificate or key file) is not displayed by the Console or the API. Defaults apply when the variable is not set; none means the feature is off or the value is worked out.

Read by the control plane and the worker

Setting	Default	What it does
`APELORA_DEPLOY_PROJECTS`	`apelora`	Incus projects Apelora may change
`APELORA_IMAGE_MIRRORS`	none	Image mirrors, upstream=mirror pairs
`APELORA_IMAGE_SERVERS`	`any`	mirrors-only refuses every server that is not a mirror
`APELORA_INCUS_CLIENT_CERT`	none	Client certificate file of the restricted deploy identity (never shown)
`APELORA_INCUS_CLIENT_KEY`	none	Private key file of the restricted deploy identity (never shown)
`APELORA_INCUS_SERVER_CERT`	none	Pinned Incus server certificate file (never shown)
`APELORA_INCUS_TLS_SERVER_NAME`	none	Name to expect in the Incus server certificate
`APELORA_INCUS_URL`	none	Incus API address; without it the mock is used
`APELORA_LOG_FORMAT`	`text`	text or json log lines
`APELORA_MAAS_API_KEY`	none	MAAS API key (consumer:token:secret) of a dedicated MAAS user; read once at start, never shown
`APELORA_MAAS_CA`	none	PEM file of the authority that signed MAAS's certificate; default the system roots
`APELORA_MAAS_URL`	none	Address of the MAAS region API (https://host:5240/MAAS); empty: only manual machines. The control plane lists its machines; the worker can fence through it
`APELORA_OTLP_ENDPOINT`	`off`	OTLP/HTTP traces for request and job spans (off, or an http(s) URL of a Tempo or collector inside the site)
`APELORA_REGION`	`default`	Constant region label on metrics
`APELORA_SECTOR`	`default`	Constant sector label on metrics
`APELORA_SITE`	`default`	Constant site label on metrics
`APELORA_WORKER_METRICS_ADDR`	`127.0.0.1:9471`	The worker's metrics and liveness listener
`DATABASE_URL`	none	PostgreSQL connection (contains a password); without it the control plane runs without sign-in on loopback only (never shown)
`RUST_LOG`	`info`	Which log lines are written

Read by the control plane only

Setting	Default	What it does
`APELORA_ALLOWED_ORIGINS`	none	Browser origins besides the API's own host
`APELORA_API_ADDR`	`127.0.0.1:8080`	Address the API listens on
`APELORA_BEHIND_PROXY`	`0`	1: a TLS-terminating proxy is in front
`APELORA_CONSOLE_ACCESS`	`enabled`	disabled turns terminal sessions off
`APELORA_CONSOLE_GID`	`1000`	Group terminal sessions run as
`APELORA_CONSOLE_IDLE_SECS`	`900`	No typing for this long ends a session
`APELORA_CONSOLE_MAX_SECS`	`3600`	Absolute limit of a session
`APELORA_CONSOLE_MAX_SESSIONS`	`3`	Open sessions and tickets per person
`APELORA_CONSOLE_POWERSHELL`	`disabled`	enabled offers PowerShell
`APELORA_CONSOLE_UID`	`1000`	User terminal sessions run as
`APELORA_DB_BACKUP_DIR`	none	Directory the database backup and restore-drill scripts write their records to (read only; Administration shows whether backups are recent and a restore was verified)
`APELORA_DRAIN_WAIT_SECS`	`30`	Seconds evacuating or restoring a member waits for its replicas to leave their service addresses; 0 skips it
`APELORA_INCUS_ADMIN_CLIENT_CERT`	none	Client certificate file of the unrestricted admin identity (never shown)
`APELORA_INCUS_ADMIN_CLIENT_KEY`	none	Private key file of the unrestricted admin identity (never shown)
`APELORA_LEGACY_TOKENS`	`enabled`	disabled refuses legacy apl_ API tokens
`APELORA_METRICS_ADDR`	`off`	Separate metrics listener without authentication
`APELORA_MOCK_WORKER`	none	1 runs the deployment worker inside the control plane on the mock cluster (development builds with the dev-worker feature only)
`APELORA_NETWORK_UPLINK`	none	Uplink for per-application OVN networks
`APELORA_OIDC_AUDIENCE`	none	Names this API has at the provider
`APELORA_OIDC_AUTHORIZED_PARTIES`	none	Clients a token must be issued to (azp)
`APELORA_OIDC_CLIENT_ID`	none	Public browser client (no secret)
`APELORA_OIDC_GROUPS_CLAIM`	`groups`	Claim holding group names
`APELORA_OIDC_ISSUER`	none	Identity provider set by the environment
`APELORA_OIDC_JWKS_URL`	none	The provider's key set
`APELORA_OIDC_LABEL`	none	Name on the sign-in button
`APELORA_OIDC_MFA_ACR`	none	acr values that count as multi-factor
`APELORA_OIDC_MFA_AMR`	none	amr values that count as multi-factor
`APELORA_OIDC_SCOPES`	`openid profile email`	Scopes the browser asks for
`APELORA_OIDC_USERNAME_CLAIM`	`preferred_username`	Claim holding the user name
`APELORA_RATE_LIMIT_FAILED_AUTH_BURST`	`20`	Refused credentials saved up per client address
`APELORA_RATE_LIMIT_FAILED_AUTH_PER_MIN`	`10`	Refused credentials per client address per minute
`APELORA_RATE_LIMIT_MAX_CLIENTS`	`10000`	Buckets kept per limit
`APELORA_RATE_LIMIT_PUBLIC_BURST`	`60`	Public requests saved up per client address
`APELORA_RATE_LIMIT_PUBLIC_PER_MIN`	`120`	Public requests per client address per minute
`APELORA_RATE_LIMIT_WRITES_BURST`	`200`	Changes saved up per signed-in caller
`APELORA_RATE_LIMIT_WRITES_PER_MIN`	`600`	Changes per signed-in caller per minute
`APELORA_RDP_GATEWAY`	`disabled`	enabled offers remote desktop sessions into Windows modules through the control plane (the person runs apelora-desktop-tunnel; not yet verified against a Windows guest)
`APELORA_SERVICE_ADDRESSES`	none	Routed IPv4 (/16–/30) or IPv6 (/112–/126) range for service addresses
`APELORA_SHARED_POOL`	none	Shared storage pool behind the data-replicated volume class (modules that restart on another server after fencing)
`APELORA_TLS_CERT`	none	Certificate chain file for HTTPS served by the API itself (never shown)
`APELORA_TLS_KEY`	none	Private key file for HTTPS served by the API itself (never shown)
`APELORA_TRUSTED_PROXIES`	none	Proxies whose X-Forwarded-For is believed
`APELORA_VOLUME_POOL`	none	Storage pool behind the data-local volume class

Read by the worker only

Setting	Default	What it does
`APELORA_ALERT_EVALUATE_SECS`	`30`	How often built-in alert rules are evaluated (0: off)
`APELORA_BACKUP_POOL`	none	Pool scheduled backups are copied to
`APELORA_BMC_ALLOW_LAB`	none	Allows the lab-only provider that stops a Lima VM (the disposable test cluster); never in production
`APELORA_BMC_FENCE_AFTER_SECS`	`30`	A server Offline for this long (at least 20) is switched off through its BMC and fenced
`APELORA_BMC_MAP`	none	File naming each server's BMC (ADR 0014): provider (redfish, ipmi, maas), address, user, the name of its password variable and its hardware UUID (for IPMI the system GUID). No passwords in it; absent: no fencing through a BMC (never shown)
`APELORA_DNS_BINARY`	none	Path of the Linux apelora-dns executable the worker copies into a resolver (default: apelora-dns next to the worker)
`APELORA_FENCE_LOCKSPACE`	none	The shared volume group's lockspace the fence probe reads; default the only one joined
`APELORA_FENCE_PROBE`	`off`	How the worker reads the shared storage's leases to fence a failed server (off or ssh)
`APELORA_FENCE_PROBE_KEY`	none	Private key of the fence probe's forced SSH command (never shown)
`APELORA_FENCE_PROBE_KNOWN_HOSTS`	none	Pinned host keys of the members the fence probe reads (never shown)
`APELORA_FENCE_PROBE_TARGETS`	none	Where the fence probe reaches each member (member=host[:port]); default the member's address, port 22
`APELORA_FENCE_PROBE_USER`	`apelora-fence`	Account of the fence probe on each member
`APELORA_HEALTH_FAIL_AFTER_SECS`	`20`	Failing checks for this long: unhealthy
`APELORA_HEALTH_RESTART_AFTER_SECS`	`60`	Unhealthy for this long: restarted
`APELORA_OUTBOX_SINK`	`log`	Where audit messages are relayed
`APELORA_PROBE_UID`	`65534`	User a module's readiness command runs as inside its instances (not root by default)
`APELORA_REBALANCE`	none	1: move a stateless replica that shares a server with another of its module (off when unset)
`APELORA_RECOVER_AFTER_SECS`	`120`	Offline time before replicas are substituted
`APELORA_RESTORE_DRILL_RECORD`	none	The restore drill's result file the restore-age alert reads
`APELORA_SUPERVISE_SECS`	`30`	Seconds between replica supervisor passes
`APELORA_UPDATE_DRAIN_SECS`	`5`	Seconds an old replica keeps running after it left its service address, for requests in flight to finish
`APELORA_UPDATE_HEALTHY_SECS`	`20`	A rolling update's new replica must pass its service's health check this long before the old one goes
`APELORA_UPDATE_TIMEOUT_SECS`	`300`	A new replica not healthy this long after it was created stops the rolling update; it is removed and the old replicas keep serving
`APELORA_WORKER_ID`	none	Worker name (default worker-<process id>)

Read by the web development server only

Setting	Default	What it does
`APELORA_API_URL`	`http://127.0.0.1:8080`	Where the web development server sends /api

Named by other settings

These variables have names an administrator chooses, so they are not listed above. Their values are secrets: read when needed, never stored, logged or shown.

Setting	Read by	What it does
`APELORA_ALERT_SECRET_<NAME>`	worker	The signing secret of an alert channel whose `secretRef` names it (alerts runbook)
`APELORA_BMC_SECRET_<NAME>`	worker	The password of a BMC whose entry in `APELORA_BMC_MAP` names it as `secretRef` (member-failure runbook)
`APELORA_SECTOR_<CREDENTIALS>_CLIENT_CERT`, `_CLIENT_KEY`, `_SERVER_CERT`	control plane	Paths of the Incus identity and server certificate of a registered sector whose `credentials` names them (ADR 0008); read when the sector is probed, never stored

Read by the DNS resolver

apelora-dns runs inside an application's resolver module, not on the servers.

Setting	Default	What it does
`APELORA_DNS_RECORDS_FILE`	`/etc/apelora-dns.records`	The service names it answers (`name address` lines), read again on every query
`APELORA_DNS_UPSTREAM_FILE`	`/etc/apelora-dns.upstream`	The resolvers it forwards every other lookup to