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.
.env versus custom.env
Section titled “.env versus custom.env”| 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.
Variables passed from .env
Section titled “Variables passed from .env”| 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_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) |
Who can sign up
Section titled “Who can sign up”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:
MAIL_MAILER=smtpMAIL_HOST=smtp.postmarkapp.comMAIL_PORT=587MAIL_USERNAME=…MAIL_PASSWORD=…Then falak-ctl up.
Domains for new services
Section titled “Domains for new services”| 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.
Runtime download mirrors
Section titled “Runtime download mirrors”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.
Build artifacts
Section titled “Build artifacts”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 |
Webhook base URL
Section titled “Webhook base URL”If git providers must reach Falak under a different hostname, set FALAK_WEBHOOK_URL (in custom.env) to that public base URL.
Apply changes
Section titled “Apply changes”sudo falak-ctl upup starts or recreates services whose definition changed, waits until healthy, recreates services whose mounted config files changed, and runs a health check.