Skip to content

Configuration

A Falak installation is configured by two files on the control plane host. After editing either, run falak-ctl up to apply. The disaster recovery bucket and passphrase live apart, in /opt/falak/dr/dr.env (falak-ctl dr setup), and the key-encryption key in /opt/falak/secrets/kek.

File Written by Reaches
/opt/falak/.env The installer (secrets and settings); you may edit it Only the variables deploy/compose.yml passes to each container
/opt/falak/custom.env You (optional) Every variable, loaded into the Laravel containers (control-plane, agent-api, horizon, reverb, scheduler)

Rule of thumb: settings listed in the table below go in .env, along with falak-ctl’s own (FALAK_BACKUP_*, FALAK_PULL, FALAK_PRUNE_IMAGES). Any other control plane setting from the environment variables reference — for example FALAK_AGENT_UPGRADE_BATCH_SIZE, FALAK_DEPLOY_WAIT_TIMEOUT_MINUTES, FALAK_WEBHOOK_URL, download mirrors (FALAK_*_MIRROR), GITHUB_APP_*, OAuth client ids — goes in custom.env.

Both files are included in falak-ctl backup. Keep them mode 600.

Area Variables
Identity of the install FALAK_DOMAIN, FALAK_URL, FALAK_VERSION, FALAK_REPO, FALAK_IMAGE_PREFIX
Image registry FALAK_REGISTRY_URL, FALAK_REGISTRY_HOST, FALAK_REGISTRY_HOST_ALIASES, FALAK_REGISTRY_USERNAME, FALAK_REGISTRY_PASSWORD
Secrets APP_KEY, DB_PASSWORD, REDIS_PASSWORD, REVERB_APP_ID, REVERB_APP_KEY, REVERB_APP_SECRET, FALAK_BUILDER_TOKEN, FALAK_OTLP_TOKEN, GRAFANA_ADMIN_PASSWORD
Agents FALAK_AGENT_API_HOST, FALAK_AGENT_API_URL, FALAK_AGENT_API_HOST_ALIASES, FALAK_AGENT_API_THREADS
Edge FALAK_TLS, FALAK_ACME_EMAIL, FALAK_ACME_CA, FALAK_HSTS, FALAK_HTTP_PORT, FALAK_HTTPS_PORT, FALAK_BIND, FALAK_EDGE_SUBNET, FALAK_DOMAIN_ALIASES
Sign-up FALAK_REGISTRATION
Domains FALAK_TEST_DOMAIN, FALAK_TEST_DOMAIN_TLS, FALAK_GENERATED_DOMAIN_SUFFIX, FALAK_DNS_RESOLVER, FALAK_DNS_DOH_URL
Mail MAIL_MAILER, MAIL_HOST, MAIL_PORT, MAIL_USERNAME, MAIL_PASSWORD, MAIL_FROM_ADDRESS
Performance FALAK_WORKER_MODE, FALAK_PHP_WORKERS, FALAK_PHP_THREADS, FALAK_PHP_MAX_THREADS, FALAK_HORIZON_MAX_PROCESSES, FALAK_LOG_LEVEL
Observability COMPOSE_PROFILES, FALAK_OTLP_ENDPOINT, FALAK_GRAFANA_HOST, FALAK_GRAFANA_URL, FALAK_GRAFANA_PUBLIC_URL, FALAK_GRAFANA_TOKEN, FALAK_LOKI_URL, FALAK_TEMPO_URL, FALAK_METRICS_QUERY_URL, FALAK_LOGS_RETENTION, FALAK_TRACES_RETENTION, FALAK_METRICS_RETENTION, FALAK_GRAFANA_PREINSTALL_DISABLED
falak-ctl FALAK_BACKUP_KEEP, FALAK_PULL, FALAK_PRUNE_IMAGES, FALAK_PREVIOUS_VERSION, FALAK_REGISTRY_GC (read by falak-ctl itself)

By default anyone who can reach the panel can create an account (and gets an empty organization of their own). On a panel reachable from the internet, set FALAK_REGISTRATION in /opt/falak/.env, then falak-ctl up:

Value Sign-up
open (default) Anyone
invite Only through an invitation link (invite from Settings → Members): the person opens the e-mailed link, chooses Sign up and registers with the invited address, which also joins the organization
closed Nobody; the Sign up links are hidden. Create accounts with falak-ctl admin create <email>

An unknown value counts as closed. A panel without any account always accepts the first sign-up, so the first administrator can register before the setting matters.

Falak sends invitations, password resets and e-mail alerts. Out of the box MAIL_MAILER=log (nothing is sent). In /opt/falak/.env:

/opt/falak/.env
MAIL_MAILER=smtp
MAIL_HOST=smtp.postmarkapp.com
MAIL_PORT=587
MAIL_USERNAME=…
MAIL_PASSWORD=…
MAIL_FROM_ADDRESS=[email protected]

Then falak-ctl up.

Variable Default
FALAK_GENERATED_DOMAIN_SUFFIX sslip.io nip.io, the domain of a self-hosted sslip.io server, or off
FALAK_TEST_DOMAIN unset Wildcard base for <slug>.<test domain>; becomes the default choice
FALAK_TEST_DOMAIN_TLS acme internal for private setups
FALAK_DNS_RESOLVER doh doh (DNS-over-HTTPS, no local cache) or system
FALAK_DNS_DOH_URL https://cloudflare-dns.com/dns-query Any DNS-over-HTTPS JSON endpoint, e.g. https://dns.google/resolve

Organizations can still pick their generated-domain provider in Settings → Domains. See Domains.

Servers download FrankenPHP, Node.js, Bun and Deno release binaries during provisioning (SHA-256 verified). To use an HTTPS mirror with the same path layout (air-gapped servers, a caching proxy), set these in /opt/falak/custom.env, then falak-ctl up:

Variable Replaces Fetched path
FALAK_FRANKENPHP_MIRROR https://github.com/php/frankenphp/releases/download <mirror>/v<version>/frankenphp-linux-<arch>
FALAK_NODE_MIRROR https://nodejs.org/dist <mirror>/v<version>/SHASUMS256.txt, node-v<version>-linux-<arch>.tar.gz
FALAK_BUN_MIRROR https://github.com/oven-sh/bun/releases/download <mirror>/bun-v<version>/SHASUMS256.txt, bun-linux-<arch>.zip
FALAK_DENO_MIRROR https://github.com/denoland/deno/releases/download <mirror>/v<version>/deno-<arch>-unknown-linux-gnu.zip{,.sha256sum}

Unset means upstream. Mirrors apply to servers provisioned (or runtimes installed) after the change.

Native build artifacts are stored on the control plane (app-storage volume) by default and served to agents through signed URLs. To use S3 instead (in custom.env):

Variable Default
FALAK_ARTIFACTS_DRIVER local (s3 to use a bucket)
FALAK_ARTIFACTS_S3_ENDPOINT, FALAK_ARTIFACTS_S3_REGION, FALAK_ARTIFACTS_S3_BUCKET —, us-east-1, —
FALAK_ARTIFACTS_S3_KEY, FALAK_ARTIFACTS_S3_SECRET —
FALAK_ARTIFACTS_S3_PREFIX, FALAK_ARTIFACTS_S3_PATH_STYLE artifacts, false
FALAK_ARTIFACTS_KEEP 10 per site

If git providers must reach Falak under a different hostname, set FALAK_WEBHOOK_URL (in custom.env) to that public base URL.

Terminal window
sudo falak-ctl up

up starts or recreates services whose definition changed, waits until healthy, recreates services whose mounted config files changed, and runs a health check.