Config as code (falak.yaml)
Since v0.11.0 a project can describe how it runs in one file at the root of its repository: falak.yaml (or falak.yml, or falak.json with the same content). The file lists the project’s units (apps, Docker Compose stacks, functions, databases, Redis/Valkey) and the environments they deploy to. On every push, Falak reads the file at the pushed commit, plans what changes, applies it, and deploys the units that changed.
- The file says how things run: build, deploy strategy, health checks, env vars, workers, schedules, domains, limits, databases, volumes, backups, previews.
- It never holds secrets or credentials: secret values stay in Falak’s secret store and the file references them (
${{ secrets.STRIPE_SECRET }}); servers, storage providers, DNS credentials and certificates are named, never defined. - What the file sets is read-only in the dashboard (“Managed by falak.yaml @ abc1234”); everything else stays editable.
- Risky changes wait for an approval (a database major upgrade, removing a production domain, changing production’s servers…). Everything else applies on push.
- It is opt-in per project. A project without a file works exactly as before.
The schema is https://falak.sh/schema/v1.json (also in the repository: contracts/config/v1.schema.json). Put $schema at the top of the file and editors with YAML/JSON schema support complete and check it as you type.
Quick start
Section titled “Quick start”-
Write the file. In your repository, on your machine:
Terminal window falak init # detects the code and writes falak.yaml, each value with the reason it was chosenfalak validate # offline: schema, environments, references (exit 5 if invalid)falak initreads the repository the way Falak’s builder does (Laravel, Symfony, Next, Nuxt, Vite, Astro, Bun, Deno, static sites, aDockerfile, acompose.yaml,.env.example, monorepo workspaces). Secret-looking values become${{ secrets.NAME }}references, never literals. Already running on Falak?falak config export -p shop -e production -o falak.yamlwrites the project’s current state as a file instead: pushing it as is changes nothing. -
Commit it to the branch your production environment deploys from (usually
main). Nothing happens yet. -
Turn it on: Project settings → Config as code: pick the source control connection, the repository and the path (
falak.yamlby default; a file in a folder works too), and enable it. Falak registers the repository’s webhook. GitHub, GitLab and Bitbucket work; plain git servers can’t be a config source yet. From the terminal:falak config source set --repo acme/shop --connection <id> --enable(the connection ids:GET /api/v1/source-control/connections).A new project hosts nothing yet, so no server is attached to it and the file can’t place a unit anywhere (
name.server). An admin lists the servers the file may use under Servers the file may place units on (orfalak config source set --allow-server app-1). A project that already runs services can use their servers without this. -
Push. The push creates a config run per environment bound to the pushed branch. Follow it in Project settings → Config as code, or from the terminal:
Terminal window falak plan # what applying would change: + create, ~ update, - delete, ! risky (with the reason)falak apply --wait # apply the local file now and stream the deploymentsfalak runs # the project's runs, newest first
A minimal file:
$schema: https://falak.sh/schema/v1.jsonversion: 1
units: web: type: app runtime: frankenphp framework: laravel php: "8.4" env: APP_ENV: production DATABASE_URL: ${{ db.DATABASE_URL }} STRIPE_SECRET: ${{ secrets.STRIPE_SECRET }} deploy: health: { path: /up } hooks: before_activate: php artisan migrate --force workers: queue: { processes: 2 } domains: [shop.example.com]
db: type: database engine: postgresql version: "17" memory: 1g backups: { cron: "0 3 * * *", storage: offsite, keep: 14 }
environments: production: branch: main servers: [web-1]How a push is applied
Section titled “How a push is applied”push ─▶ environments bound to the branch ─▶ read the file at the commit ─▶ validate ─▶ plan ─▶ risky? ── yes ─▶ wait for an approval ─┐ │ no │ approved ▼ ▼ phase A (before any build) ─▶ deploy the units that changed ─▶ phase B (when each release is live)- Which environments. Those whose
branchis the pushed branch, read from the file at the pushed commit. An environment withoutbranchis applied only from the CLI (falak apply -e staging) or the dashboard (Apply now). A file withoutenvironmentsbinds the project’s production environment to the repository’s default branch. - Validate. Four stages, each stopping the next on an error: reading (YAML/JSON), the schema, the merge of the environment’s overrides and the references, and the organization checks (servers, secrets, storage, names, bounds). Errors point at the line and column.
- Plan. Every change with its operation (
create,update,delete,detach,noop) and, when risky, the rule and the reason. The plan is shown on the run, infalak plan, and on pull requests. - Phase A, before any build: environments, databases and Redis, sites and their build settings, env vars, deploy settings, limits, function settings, volumes, previews. A failure here stops the run and touches no running release.
- Deploy each unit that changed: files under its
rootchanged in the push, or its config changed. Units that didn’t change are not redeployed. (When the push can’t list its files — Bitbucket, a force push, 20 commits or more — every unit counts as changed.) - Phase B, when each unit’s release is live (every server activated and the health checks passed): workers, daemons, schedules, domains, redirects, headers, mounts, function schedules, Laravel’s scheduler/Horizon/Octane. A failed deployment never gets them, and a phase B that fails fails the run.
- Saved on the release. Each release keeps the unit’s config; rolling back restores it (see Rollbacks).
One push makes one run per environment, never one per site: a repository with 30 units plans once per environment. Runs of an environment apply one at a time, and a newer run supersedes the older ones not finished yet.
A pull request gets the plan for its target environment as a comment and a falak/config commit status. Nothing is applied until it is merged.
The file
Section titled “The file”$schema: https://falak.sh/schema/v1.json # optional, for editorsversion: 1 # required, always 1units: { … } # required: the deployable units, by keyenvironments: { … } # the environments the file deploys to, by slugpreviews: { … } # pull request previewsUnits are keyed by name: lower case letters, digits and dashes, starting with a letter (web, api, db; secrets is reserved). The key is the service’s name on the project canvas and the name ${{ <unit>.KEY }} references use. A file holds at most 100 units and 20 environments.
Values:
- Durations: whole numbers with units from largest to smallest:
30s,5m,1h30m,2d,0s. No bare numbers, no fractions, noms. - Sizes: binary multiples, case-insensitive, with an optional
b/ib:512m=512MiB=512MB;1.5g= 1536 MiB. Each field says the unit it must be a whole number of (MiB for memory, GiB for a databasedisk). - CPUs: a number of cores (
0.5,2). - Versions are strings: quote them (
php: "8.4",version: "17").php: 8.4is a number and fails the schema. - YAML 1.2 rules:
yes/no/on/offare strings, not booleans;0755is a string; an unquoted date (2026-10-11) is an error (quote it). Anchors and aliases (&defaults,<<: *defaults) work.
The file manages only what it sets. A field you leave out keeps today’s value and stays editable in the dashboard; removing a field from the file makes it editable again, it is never reset to a default. A new unit gets the defaults listed below.
Unit types
Section titled “Unit types”type |
What it is | Notes |
|---|---|---|
app |
A site: PHP (FrankenPHP, PHP-FPM), Node, Bun, Deno, static, or a Docker image | Workers, daemons, schedules, volumes |
compose |
A Docker Compose stack from the repository | Falak settings per compose service |
function |
A cloud function, code from the repository under root |
Scales to zero (Functions) |
database |
A PostgreSQL, MySQL or MariaDB container | Never deleted by the file |
redis |
A Redis or Valkey container | Never deleted by the file |
Every unit has type; app, compose and function units also have root, servers, env, domains and the fields below.
Fields of every deployable unit (app, compose, function)
Section titled “Fields of every deployable unit (app, compose, function)”| Field | What | Default |
|---|---|---|
type |
app, compose, function, database or redis |
required |
root |
The unit’s directory in the repository. A push changing files under it redeploys the unit | . |
servers |
Names of servers attached to the project (hosting one of its services, or allowed by an admin in Project settings → Config as code). The first one leads (migrations, the scheduler) | the environment’s servers |
env |
Environment variables: literals and references (see References); at most 500 | — |
expose |
Variables also given to the deploy hooks and the build (VITE_*, NEXT_PUBLIC_* always are) |
— |
domains |
Domains served by the unit (below) | — |
env keys merge into the unit’s current variables: a key you drop from the file stays, no longer managed. Integers and booleans are stored as text (true, 42); floats must be quoted.
app units
Section titled “app units”units: web: type: app root: apps/web runtime: php-fpm # frankenphp | php-fpm | node | bun | deno | static | docker framework: laravel # laravel | symfony | statamic | wordpress | php | next | nuxt | node | static | docker php: "8.4" # node: "22" for Node runtimes web_directory: public health_path: /up test_domain: false build: { mode: native } # native | docker | on-server; dockerfile: Dockerfile laravel: { scheduler: true, horizon: false, octane: false } limits: { memory: 1g, cpus: 1 }| Field | What | Default |
|---|---|---|
runtime |
frankenphp, php-fpm, node, bun, deno, static or docker |
— (required for a new unit) |
framework |
Sets defaults such as the web directory and the deploy script | from the runtime; laravel for a new unit on a PHP runtime with a laravel block |
php / node |
PHP version ("8.4") / Node.js major version ("22"), among the versions the installation offers |
the installation’s |
web_directory |
The public directory served, relative to root (public, dist) |
the framework’s |
port |
docker runtime: the port the app listens on inside its container |
— |
image |
docker runtime: deploy this prebuilt image instead of building (ghcr.io/acme/web:1.2) |
— |
health_path |
The unit’s health path: deploys wait for it on the new release (unless deploy.health.path is set), and the edge checks it to keep each server in rotation (2xx only, so not a path that redirects) |
deploys check /; no edge check |
test_domain |
Also serve on the installation’s test domain | true |
build.mode |
native (Railpack on a builder), docker (an image from a Dockerfile) or on-server (built on each server) |
native |
build.dockerfile |
docker mode: the Dockerfile, relative to root |
Dockerfile |
laravel.scheduler |
Run php artisan schedule:run every minute on the leader |
false |
laravel.horizon |
Run Horizon | false |
laravel.octane |
Serve with Octane: false, frankenphp, swoole or roadrunner |
false |
deploy |
Deploy settings (below) | — |
workers, daemons, schedules |
Processes (below) | — |
redirects, headers, mounts |
Edge rules (below) | — |
limits |
Resource limits (below); not for static units, and only log, restart, oom on FrankenPHP (the shared edge) |
— |
volumes |
docker runtime only (below) |
— |
A unit the file adds is created as the dashboard would create it: a Laravel unit (framework laravel; not a docker or compose unit, whose image is opaque to Falak: give those APP_KEY: ${{ secrets.APP_KEY }}) gets a generated APP_KEY, APP_NAME and APP_URL unless the file sets them.
compose units
Section titled “compose units”units: shop: type: compose root: stack files: [compose.yaml, compose.prod.yaml] profiles: [web] deploy: { strategy: rolling } domains: [shop.example.com] # the first public service's services: front: { port: 80, health_path: /up, limits: { memory: 256m } } api: { port: 8080, domains: [api.example.com] } db: { replace_with: db } # run this service as the `db` database unit instead| Field | What | Default |
|---|---|---|
files |
Compose files relative to root, in -f order |
compose.yaml (or docker-compose.yml) |
profiles |
Compose profiles to enable | — |
test_domain |
Serve public services on the installation’s test domain too | true |
services.<name>.port |
Makes the service public: the port it listens on inside its container | — |
services.<name>.health_path |
Path checked before it goes live | — |
services.<name>.domains / redirects / headers |
That service’s routes (needs port) |
— |
services.<name>.limits |
That service’s limits, over its own compose limits | — |
services.<name>.replace_with |
Run the service as a Falak database instead: the key of a database or redis unit; its references are rewritten to that unit |
— |
The unit’s own domains, redirects and headers go to its first public service. Public services keep their order once created; a service the file makes public is added last, and removing its port stops managing it (it stays public). Host bind mounts are an administrator’s choice in the dashboard and can’t be set from the file. Compose units can’t mount Falak volumes yet (their compose file declares what each service mounts). See Compose apps from git.
function units
Section titled “function units”units: hooks: type: function root: functions/hooks runtime: bun # bun | node | deno | python | go entrypoint: index.ts memory: 512m cpus: 0.5 timeout: 1m scaling: { min_instances: 0, max_instances: 5, concurrency: 50, idle_timeout: 5m } access: { allow: [10.0.0.0/8] } schedules: nightly: { cron: "0 3 * * *", timezone: Europe/Berlin, overlap: skip, timeout: 5m }| Field | What | Default |
|---|---|---|
runtime |
bun, node, deno, python or go |
— |
entrypoint |
The entry file, relative to root |
the runtime’s (index.ts, main.py, main.go…) |
memory / cpus / timeout |
Per instance: 64m–16g / 0.1–16 / request timeout 1s–15m | 256m / 0.5 / 30s |
scaling.min_instances |
Instances kept warm (0–20) | 0 |
scaling.max_instances |
1–50, at least min_instances |
5 |
scaling.concurrency |
Requests one instance handles at once (1–10000) | 50 |
scaling.idle_timeout |
Stop an idle instance after (10s–1d) | 5m |
access.allow |
Only these addresses (CIDRs) may call it. API keys are created in the dashboard, never here | — |
schedules.<name> |
cron, timezone, overlap (skip/allow), timeout (default 5m), enabled |
— |
A function’s code is the repository’s files under root at the run’s commit: dot-files, node_modules, __pycache__, .venv/venv and the config file itself are left out; the rest must fit a function version (50 files, 1 MB, the entrypoint present). A new version is saved only when the code changed, and the dashboard’s editor no longer deploys a function whose code the file manages (rolling back to a version still works). A function the file creates gets no default domain: reach it through its domains or another unit’s mounts.
database and redis units
Section titled “database and redis units”units: db: type: database engine: postgresql # postgresql | mysql | mariadb version: "17" # the major line server: db-1 memory: 2g cpus: 2 disk: 50g settings: { max_connections: 200 } databases: [shop, analytics] public: false require_tls: true backups: cron: "0 3 * * *" storage: offsite keep: 14 keep_days: 30 databases: [shop] encryption: { mode: customer, recipient: age1… } drill: monthly drill_query: select 1 from users limit 1 pitr: { storage: offsite, window_days: 7, base_interval_days: 1 }
cache: type: redis engine: valkey # redis | valkey memory: 256m| Field | What | Default |
|---|---|---|
engine |
postgresql, mysql, mariadb / redis, valkey. A run never changes it: a new engine is a new unit |
redis for redis units |
version |
The major version ("17", "8.4", "11.4", "8", "8.1"). A change is a major upgrade: risky; a downgrade is refused |
the newest Falak supports |
server |
The server it runs on. A run never moves a database (the Databases page does, from backups) | the environment’s first server |
memory |
Memory limit; the engine is tuned to it (whole MiB) | — |
cpus |
CPU cores (0.1–256) | — |
disk |
Size of its data volume (whole GiB, 1g–16t); it only grows | a Docker volume without a size |
settings |
Engine settings (see Limits and settings) | — |
public |
Publish the port, only to allowed_sources. Turning it on is risky |
false |
allowed_sources |
public: addresses (CIDRs) allowed to connect |
— |
require_tls |
Refuse unencrypted connections | false |
databases |
database units: the databases in the container |
one named after the key (- as _) |
backups.cron |
When (5 fields, UTC) | — |
backups.storage |
The name of a storage provider the project already uses, or one an admin allowed | — |
backups.keep / backups.keep_days |
Keep at most N successful backups per database / delete those older than N days | — |
backups.databases |
Databases backed up | all of the unit’s |
backups.encryption.mode / .recipient |
cp (Falak’s key) or customer (your age1… recipient) |
— |
backups.drill / drill_query / drill_server |
Restore drills (off, weekly, monthly), a read-only SELECT that must return rows, another server to run them on |
off |
backups.enabled |
true |
|
pitr.enabled / storage |
Point-in-time recovery (PostgreSQL, MySQL, MariaDB): continuous archiving | on when the block is present |
pitr.window_days / base_interval_days |
Recovery window (1–35) / a new base backup every N days (1–35) | 7 / 1 |
pitr.encryption |
As backups.encryption |
— |
Passwords are Falak’s: generated when the container is created and never in the file, a plan, a run, an export or a pull request comment. The container’s first user gets every database the file adds. A change of memory, cpus, settings, require_tls or public restarts the container (the plan says so); allowed_sources applies live and disk grows online. A major version upgrade must be the only change to that unit in its push. See Backups and Point-in-time recovery.
Deploy
Section titled “Deploy”deploy: strategy: rolling batch_size: 1 keep_releases: 5 secrets: env health: { enabled: true, path: /up, status: 200, timeout: 10s, retries: 3, retry_delay: 5s } watch: { minutes: 15, on_trigger: rollback, health: true, health_failures: 3, crashes: true, errors: true, issues: false } hooks: before_fetch: echo starting before_activate: php artisan migrate --force after_activate: php artisan optimize after_restart: php artisan horizon:terminate| Field | What | Default |
|---|---|---|
strategy |
Host runtimes: zero-downtime, in-place, rolling, canary; docker: blue-green, rolling, canary; compose: compose, rolling, canary. Changing it in production is risky |
the first of those |
batch_size |
rolling: servers switched at a time (1–100) |
1 |
keep_releases |
Releases kept on each server for rollbacks (1–50) | 5 |
secrets |
docker runtime: env, or files (secret variables as /run/secrets files) |
env |
health.enabled / path / status |
The check on the new release before it goes live (blue/green swaps too); path only for deploys, not the edge |
true / the unit’s health_path, else / / 200 |
health.timeout / retries / retry_delay |
One attempt (1s–2m) / attempts (1–30) / wait between (0s–5m) | 10s / 3 / 5s |
watch.enabled |
Watch the release after it went live | true when the block is present |
watch.minutes / on_trigger |
How long (1–60) / rollback or alert_only |
5 / rollback |
watch.health / health_failures |
Trigger: the health check fails N times in a row (1–20) | true / 3 |
watch.crashes |
Trigger: an OOM kill or a restart loop | true |
watch.errors |
Trigger: the 5xx rate goes above max(baseline × 3, 5%) | true |
watch.issues |
Trigger: a new error issue in Insights | false |
hooks.before_fetch, before_activate, after_activate, after_restart |
Commands of the deploy script’s sections | the framework’s |
Each hook you set replaces only that section of the deploy script; the hooks you leave out keep today’s commands (for Laravel: optimize, storage:link and the leader-only migrate). Compose units have no hooks. See Deployment strategies, Watch after deploy and Deploy scripts.
Processes (app units)
Section titled “Processes (app units)”workers: default: { queue: [high, default], processes: 2, timeout: 90s, tries: 3, backoff: 10s, memory: 256m } emails: { connection: redis, queue: [mail], max_jobs: 1000, max_time: 1h } reports: { command: node worker.js, processes: 1, servers: [web-2] }daemons: reverb: { command: php artisan reverb:start, instances: 1, restart: always, stop_signal: TERM, stop_timeout: 30s }schedules: prune: { command: php artisan model:prune, cron: "0 4 * * *", timezone: Europe/Berlin, overlap: skip, timeout: 1h } ping: { command: curl -fsS https://hc.example.com/ping, cron: "@every 5m", heartbeat: false, all_servers: true }Workers (workers.<name>):
| Field | What | Default |
|---|---|---|
command |
The start command. Without it the worker runs queue:work, which only Laravel units have |
queue:work (Laravel) |
connection / queue |
Queue connection / queue names in priority order | — |
processes |
Processes per server (1–64) | 1 |
timeout / sleep / backoff |
Job timeout (0s = none, ≤ 1d) / sleep when the queue is empty (≤ 1h) / wait before a retry (≤ 1d) | 60s / 3s / — |
tries / max_jobs / max_time |
Attempts per job (0 = unlimited, ≤ 1000) / restart after N jobs / restart after running this long (≤ 7d) | 1 / — / — |
memory |
Memory a worker may use before it restarts (32m–64g) | 128m |
env |
Extra literal variables (no references; the worker already sees the unit’s env); at most 50 | — |
limits |
Resource limits of the worker | — |
servers |
Run only on these servers of the unit | all of them |
Daemons (daemons.<name>): command, directory (working directory; default the current release), instances (1–64, default 1), restart (always, on-failure, never), stop_signal (TERM, INT, QUIT, HUP, KILL, USR1, USR2), stop_timeout (1s–1h, default 30s), env, limits, servers, user.
Schedules (schedules.<name>): command, cron (5 fields, @hourly, @daily, @weekly, @monthly, @yearly, or @every 90s), timezone (IANA, default UTC), overlap (skip by default: don’t start while the previous run is going; allow), timeout (1s–1d, default 1h), heartbeat (alert on missed or failed runs, default true), enabled, all_servers (run on every server instead of the leader), user.
user: processes from the file always run as the unit’s site user. Leave user out, or write exactly that user; anything else (including root) is refused.
A worker made in the dashboard without a name reads as worker-1, worker-2… (creation order) in an export; a file using that key adopts the worker and names it. See Processes, workers and cron.
Domains and edge rules
Section titled “Domains and edge rules”domains: - shop.example.com # a plain host - name: www.shop.example.com www: to_apex # none | to_www | to_apex - name: "*.shop.example.com" tls: dns # auto | dns | custom | internal | off dns_credential: cloudflare-main - name: legacy.example.com tls: custom certificate: legacy-2026 primary: true cloudflare: { proxied: true, cache: standard } # standard | everything | bypassredirects: - { from: /old, to: /new } - { from: "/blog/*", to: https://blog.example.com, status: 302 } # 301 | 302 | 307 | 308headers: X-Frame-Options: DENY Strict-Transport-Security: max-age=31536000mounts: - { path: /api, function: hooks, strip_prefix: true }| Field | What | Default |
|---|---|---|
domains[] |
A host name, or an object with name |
— |
primary |
The primary domain (APP_URL, links) |
the first in the list |
www |
none, to_www (apex → www) or to_apex (www → apex) |
none |
tls |
auto (ACME HTTP), dns (ACME DNS challenge, needs dns_credential; required for wildcards), custom (needs certificate), internal (Caddy’s internal CA), off (plain HTTP) |
auto |
dns_credential / certificate |
The name of an existing DNS credential / uploaded certificate | — |
cloudflare.proxied / cloudflare.cache |
For a domain in a Cloudflare zone Falak manages (Cloudflare) | the zone’s |
redirects[] |
from (a path matcher: /old, /blog/*), to (an absolute URL or a path), status |
status: 301 |
headers.<Name> |
A response header added to every response | — |
mounts[] |
path (a prefix, no trailing slash), function (the key of a function unit), strip_prefix |
strip_prefix: true |
A host can belong to one unit of one environment. A DNS credential or certificate the file names must already be used by the project’s domains, uploaded for one of its sites, or listed by an admin in Project settings → Config as code (Allowed credentials). Removing a production domain is risky. See Domains, TLS certificates and Routing rules.
Limits
Section titled “Limits”limits on an app unit, a compose service, a worker or a daemon:
| Field | What |
|---|---|
memory |
Hard memory limit (whole MiB, at least 32m) |
memory_reservation |
Memory kept for the service (at most memory) |
cpus |
CPU cores, fractional (0.05–1024) |
pids |
Most processes and threads (16–4194304) |
restart |
Restart policy: always, unless-stopped, on-failure |
max_restarts |
on-failure: give up after N restarts (1–1000) |
log.max_size / log.max_files |
Log rotation: size of one file (1m–10g) / files kept (1–100) |
oom |
protect (the kernel kills other processes first) or normal |
Limits are checked against the unit’s servers. Static units have nothing to limit, and FrankenPHP units run inside the shared edge (no memory, memory_reservation, cpus or pids: use Octane workers, or the php-fpm runtime). See Resource limits.
Volumes
Section titled “Volumes”app units with the docker runtime can mount Falak volumes:
volumes: uploads: mount: /srv/uploads backups: { cron: "0 4 * * *", storage: offsite, keep: 7, consistency: pause } cache: kind: sized size: 512m mount: /cache read_only: true protected: true server: web-1| Field | What | Default |
|---|---|---|
kind |
docker (a Docker named volume) or sized (a fixed-size volume, needs size). Can’t change later |
docker |
size |
sized: the size (whole MiB). It only grows |
— |
mount |
Absolute path in the container | — |
service |
Compose units: the compose service it is mounted in (not supported yet) | — |
read_only |
Mount read-only | false |
protected |
Refuse deleting the volume until this is turned off | false |
server |
The server it lives on (a run never moves a volume) | the unit’s first server |
backups.cron / storage / keep / keep_days |
As for databases | — |
backups.consistency |
none, pause or stop the services using the volume while it is archived |
none |
backups.encryption / drill / drill_server / enabled |
As for databases | — |
Volume names are lower case letters, digits, ., _ and -. Host paths (bind mounts) are never in the file. See Volumes.
Environments and branches
Section titled “Environments and branches”environments: production: branch: main production: true servers: [web-1, web-2] staging: branch: develop servers: [staging-1] units: web: domains: [staging.shop.example.com] deploy: { strategy: in-place } env: { APP_ENV: staging } worker-only: { type: app, runtime: node, node: "22", root: tools/worker } analytics: null| Field | What |
|---|---|
branch |
A push to this branch applies the file to this environment. Without it, only falak apply or the dashboard apply it |
production |
A production environment: its risky changes need an approval. Changing it is itself risky |
servers |
The default servers of every unit of the environment; a database unit’s default server is the first |
units |
Overrides of units in this environment, by unit key |
Keys are the project’s environment slugs. One repository can feed several environments (main → production, develop → staging). See Projects and environments.
Overrides merge over units: maps merge key by key, lists (domains, redirects, mounts, servers) replace, and null removes a key. units.<key>: null removes the unit from that environment; a key that isn’t in units adds an environment-only unit (it needs type). An override can’t change a unit’s type. Workers, daemons, schedules, volumes, headers and compose services are maps precisely so an environment can change one entry.
New environments. A push to production’s branch creates every environment the file declares and the project doesn’t have yet (empty, named after the key, not production). A push to another branch naming an unknown environment fails its run. falak apply -e <new> also creates it, for someone who may manage projects. falak plan -e <new> shows the plan as a preview of its creation.
Removing an environment from the file releases it: its sites deploy the old way again (push to deploy), its fields become editable and its waiting runs are cancelled. Nothing is deleted.
Previews
Section titled “Previews”previews: enabled: true base: staging # the environment previews copy units: web: include # include (default) | share | omit docs: omit db: { strategy: clone_sanitize, source: production, sanitize: { sql: "update users set email = concat(id, '@example.test')" } } server: preview-1 fork_server: forks-1 variables: [STRIPE_KEY] domain_pattern: "pr-{number}-{service}" max_concurrent: 5 idle_ttl: 3d access: basic # basic (HTTP basic auth) | public acknowledge_shared_database: false| Field | What | Default |
|---|---|---|
enabled |
Previews for pull requests | true when the block is present |
base |
The environment previews copy (required when enabled; the file must deploy to it) | — |
units.<key> |
include, share (use the base environment’s service), omit, or for a database unit {strategy, source, sanitize} |
include |
strategy |
empty, clone_backup (the latest backup of source) or clone_sanitize (that backup, then sanitize.sql or sanitize.command) |
empty |
source |
The environment whose backup is cloned | base |
server / fork_server |
The server previews run on / a server for pull requests from forks | the base’s first server / — |
variables |
Variables previews copy from the base environment’s units | — |
domain_pattern |
Host label under the organization’s preview domain; holds {number} and {service} ({project} works too) |
pr-{number}-{service} |
max_concurrent / idle_ttl |
Previews at once (1–50) / delete a preview idle this long (whole hours, 1h–30d) | 5 / 3d |
access |
basic or public |
basic |
acknowledge_shared_database |
Allow share of a database unit (previews then write to it) |
false |
The block is applied by the run of its base environment (production’s when it names none) and is the stored copy of the dashboard’s preview settings. A preview is built from the pull request’s file, so a config change can be tried before merging; a pull request from a fork always uses the base branch’s file (after the usual /falak preview approval), and never creates new units. Data strategies, sharing, the server and access always come from the base branch’s settings, so a pull request can’t widen what data reaches its preview. Copying production data into previews (clone_backup/clone_sanitize from production, or a script run on such a copy) and sharing a database are risky.
References
Section titled “References”env values can reference the secret store and other units:
env: STRIPE_SECRET: ${{ secrets.STRIPE_SECRET }} DATABASE_URL: ${{ db.DATABASE_URL }} REDIS_URL: ${{ cache.REDIS_URL }} API_URL: https://${{ api.APP_HOST }}/v1${{ secrets.NAME }}: a secret of the store, the nearest scope of the unit’s service (service, environment, project, organization).NAMEis upper case letters, digits and_. It must exist when the file is planned:falak secret set NAMEsets a project secret before the first push (-e ENVfor one environment).${{ <unit>.<KEY> }}: another unit’s variable. Adatabaseunit exposesDATABASE_URL,DB_CONNECTION,DB_HOST,DB_PORT,DB_DATABASE,DB_USERNAME,DB_PASSWORD; aredisunitREDIS_URL,REDIS_CLIENT,REDIS_HOST,REDIS_PORT,REDIS_PASSWORD; an app, compose or function unit the keys of itsenv. A name that isn’t a unit of the file must be a service on the environment’s canvas.- References work only in a unit’s
envvalues. They are resolved at deploy time, never stored resolved: a reference in hooks, commands or a worker’senvis an error. - A unit referencing a database on another server needs both servers in a private network (Network → Private networks); otherwise its deployment fails with the reason.
See Variable references.
Risky changes and approvals
Section titled “Risky changes and approvals”A plan with a risky change waits for an approval instead of applying. Nothing of it is applied (and nothing is deployed) until someone with config.approve approves it. The rules (contracts/config/risky-changes.json):
| Rule | When |
|---|---|
database.version |
A database or Redis major version changes (a major upgrade) |
database.public |
A database is made public |
database.backups_removed, database.backups_disabled, volume.backups_removed, volume.backups_disabled |
A backup schedule is removed or disabled |
database.backups_retention, volume.backups_retention |
Fewer backups kept, or for fewer days |
database.backups_databases_removed |
A database dropped from the backup schedule |
database.pitr_off, database.pitr_removed, database.pitr_window |
Point-in-time recovery turned off, removed, or its window shortened |
database.database_removed |
A database removed from a unit’s databases |
volume.delete |
A volume removed from the file |
unit.delete, unit.remove_with_data, unit.remove_with_volumes |
A unit removed from the file (any; one holding data; one with volumes) |
production.strategy, production.servers, production.domain_removed, production.drill_server |
In a production environment: the deploy strategy, the servers, a removed domain, the drill server |
environment.production |
An environment becomes production or stops being one |
previews.production_data, previews.shared_database |
Previews get production data, or share a database |
Approving. In Project settings → Config as code, the waiting run shows its risky changes with their rule and reason; Approve or Reject, with an optional comment. From the terminal: falak approve <run> / falak reject <run>, or falak apply --wait --approve. An approval covers exactly the risky changes shown: when you approve, the run plans again, and if a risky change appeared that you didn’t see, nothing is applied and the run waits again (“The plan changed since it was shown; review it again.”).
- Admins have
config.approveby default. A project can require a different approver than the person who requested the run (Project settings → Config as code; a push run has no requester, so it never blocks those). - A waiting run expires after 7 days (
FALAK_CONFIG_APPROVAL_DAYS), and a newer run of the environment supersedes it. Disabling the source cancels it. - A waiting run alerts
config.run.awaiting_approvalthrough the organization’s alert rules, and the pull request it merged gets a note with the run’s link.
Ownership, read-only fields and unmanaged resources
Section titled “Ownership, read-only fields and unmanaged resources”- Every field and resource a run applies is recorded as managed by the file. The dashboard shows it read-only with the badge “Managed by falak.yaml @ abc1234” and a link to the file at that commit; the server refuses (422) an edit that changes a managed value. Fields the file doesn’t set stay editable.
- A managed service can’t be renamed or deleted in the dashboard: rename or remove the unit in the file.
Removing things from the file:
| Removed from the file | What happens |
|---|---|
| A field | It is no longer managed: editable again, value kept |
| An env key | It stays with its value, no longer managed |
| A worker, daemon, schedule, domain, redirect, header, mount, function schedule | Deleted if the file created it and its unit is still managed; otherwise detached (kept, unmanaged). Removing a production domain is risky |
| An app, compose or function unit | Detached: the service keeps running, unmanaged. Deleted only by falak apply --allow-destroy (config.destroy) and only if the file created it |
| A database or Redis unit, a database, a volume, a backup schedule | Detached, never deleted by a push. falak apply --allow-destroy deletes one the file created; a volume another site or service still mounts is never deleted; a database container’s data volume is kept |
What a run detached is listed in Project settings → Config as code → Unmanaged resources (and falak config unmanaged): delete it there through its own module’s page and permissions, or add it back to the file to manage it again.
Falak compares each environment with the file last applied to it every 30 minutes (FALAK_CONFIG_DRIFT_MINUTES): changes made outside the file’s locks (another API, a module, a server) show as drift. A drifted environment gets a banner on the canvas, an alert config.drift (once per distinct drift), and falak drift lists the changes a run would make to put the file back. Push the file again (or Apply now) to restore it. unknown means nothing was applied yet, or a run is applying: it is not drift.
Rollbacks
Section titled “Rollbacks”Each release keeps the config of its unit. Rolling back a unit (dashboard, falak rollback, or the release watch) re-applies the config saved on the release it returns to, as a rollback run, without a new deployment. A rollback has no approval, so it skips every risky change (each listed as a warning rollback.risky_skipped) and never creates data resources (a database, Redis, a volume): adding them back takes a push. Rolling back to a release made before the file existed restores the code only (warning rollback.no_config).
Turning it off and on
Section titled “Turning it off and on”- Disabling the source (Project settings → Config as code) keeps every resource, makes every field editable again, cancels runs that wait for an approval, and gives the sites back to push to deploy. Nothing is deleted.
- Re-enabling it: the next push plans the file against today’s state; the file wins for the fields it sets (changes made while it was off show in that plan).
- Adopting a running project:
falak config export -e production -o falak.yaml, commit, enable, push. The export holds today’s state (units, the environment with its branch, previews), so the first run’s plan is empty: nothing is redeployed beyond the push’s own deployment, nothing is deleted. Exports without thesites.env.viewpermission leave literal env values out (references are kept), which also plans empty.
The CLI
Section titled “The CLI”Install and log in: see Install and log in (the commands need CLI v0.11.0). The project comes from -p (id or name), then FALAK_PROJECT, then .falak/project.json (written by falak init when you pick a project). The environment comes from -e, else the one whose branch is the current git branch (production for a file without environments). The file defaults to falak.yaml, then falak.yml, then falak.json.
| Command | What |
|---|---|
falak init [dir] |
Write falak.yaml from the code. --yes (ask nothing), --stdout, --json (the detection report), --full (write defaults too), --force (replace a file), --dockerfile (a starter Dockerfile for Go, Python, Ruby, Rust, Java), --update (a diff of what the code adds; --write applies it) |
falak validate [file] |
Check the file offline (schema, environments, references); logged in with a linked project, also the organization checks. -e, --format yaml|json, --offline |
falak plan [file] |
What applying the local file would change. -e, -p, --json |
falak apply [file] |
Apply the local file now. --wait (stream the deployments; --timeout, default 30m), --approve [--yes] [--comment], --allow-destroy |
falak runs list / falak runs show <run> |
Runs newest first (--limit); one run’s plan, approval and deployments |
falak approve <run> / falak reject <run> |
Decide a waiting run. --comment, --yes |
falak drift |
The environment against its last applied file. --check checks now |
falak config export [project] |
Today’s state as a file. -e, -o FILE, --format yaml|json |
falak config unmanaged |
What runs detached |
falak secret set NAME / list / delete NAME |
The project’s secrets (-e ENV: one environment’s). set reads the value from a hidden prompt or stdin, never an argument, and adds a version when the secret exists; --from-env FILE imports a .env file. list shows names, never values. CLI v0.11.1 |
falak config source show / falak config source set |
The file the project follows. set changes only what its flags name: --repo owner/name, --connection <id>, --path falak.yaml, --enable / --disable (a new source is enabled), --allow-server NAME (repeatable; replaces the list, "" clears it; admins only) |
--json prints the API’s data as is. Issues print as falak.yaml:12:17: schema: /units/web/deploy/strategy: value must be one of …. Full flags: CLI commands.
Exit codes
| Code | Meaning |
|---|---|
0 |
Done (for drift: in sync, or unknown) |
1 |
An error (the run failed in phase A or B, the API refused, --wait gave up) |
2 |
Wrong usage |
3 |
A unit’s deployment failed |
5 |
The file is invalid |
6 |
The run waits for an approval |
7 |
drift: the environment drifted |
The API behind them is in API.md (“Config as code”).
Security model
Section titled “Security model”Whoever can push to the repository can change how the project runs. They cannot reach anything the project doesn’t already have:
| A pusher can | A pusher can’t |
|---|---|
| Change units, builds, deploy settings, hooks, processes, domains, limits, previews of this project | Read or write secret values (only reference secrets that already exist) |
| Create units, databases, Redis, volumes and backups on servers attached to the project (hosting one of its services, or allowed by an admin) | Use a server not attached to the project, or create servers |
| Reference storage providers, DNS credentials and certificates the project already uses (or an admin allowed) | Define credentials, firewall rules, private networks, teams, roles or tokens |
| Remove resources from the file (they are detached) | Delete data (databases, volumes) without config.destroy and --allow-destroy |
| Propose risky changes | Apply a risky change without someone with config.approve |
| Run processes as the unit’s site user | Run processes as another user (root, sudo users), or mount host paths |
- Pull requests only get a plan comment; a fork’s pull request never supplies config (its preview uses the base branch’s file).
- Env values are masked (
••••) in stored plans, in pull request comments, and in API answers for callers withoutsites.env.view; database passwords never leave Falak. - Deploy hooks already ran the repository’s commands before config as code; the file doesn’t widen that.
Permissions
Section titled “Permissions”Organization roles; the owner has all. See the permissions reference.
| Permission | What | Default roles |
|---|---|---|
config.view |
Validate, plan, export, read runs, drift and unmanaged resources | Admin, Developer, Viewer |
config.apply |
Create runs (falak apply, Apply now), cancel them, connect / enable / disable the source |
Admin, Developer |
config.approve |
Approve or reject runs with risky changes; change who may approve and the allowed credentials | Admin |
config.destroy |
Runs with allow_destroy (delete what the file removed, data included) |
Admin |
API tokens need these abilities too: a token made with a list of abilities before config as code doesn’t have them.
Schema versions
Section titled “Schema versions”- Every file says
version: 1. Version 1 only gains optional fields: a file valid today stays valid in every later Falak release, and a new field never changes what an existing file means. - A breaking change (a field removed or renamed, a type narrowed, a value no longer accepted, a new required field) is a new version:
version: 2, with its own schemahttps://falak.sh/schema/v2.json. - Falak accepts every published version it knows, so upgrading Falak never breaks your file; you move a file to a new version when you choose to.
- The released v1 schema is frozen in
contracts/config/v1.baseline.json; a contract test fails whenv1.schema.jsonwould narrow it.
For editor completion, start the file with:
$schema: https://falak.sh/schema/v1.jsonLimits and known gaps
Section titled “Limits and known gaps”- At most 100 units, 20 environments, 500 env vars per unit, 50 workers per unit; function code 50 files / 1 MB.
- Plain git servers (no provider API) can’t be a config source yet.
- Compose units can’t mount Falak volumes; volumes need the
dockerruntime. - The file never manages database users, function API keys, firewall rules, private networks, alert channels or teams; servers, storage providers, DNS credentials and certificates are named only.
- A run never changes a database engine, moves a database or volume, shrinks a disk or changes a volume’s kind (the dashboard’s actions do).
- Two environments of the same push claiming the same host both pass validation; the second one’s phase B fails with “This domain is already in use.” Give each environment its own hosts (overrides).
- A unit referencing a database on another server without a private network passes validation and fails at deploy time with the reason.
- A plan reads each unit’s resources one by one (about 40 queries per unit); a 40-unit file plans in well under a second.
- Previews of a fork never create units the base environment doesn’t have.
- Previews from a pull request’s file and rollback restoring a release’s config are covered by the test suites but were not exercised on live servers.