Builders

A builder turns a commit into an artifact or image. Every installation has one; add more for Docker builds or more capacity.

Kinds of builders

Builder	Setup	Modes	Serves
Control plane host (builder service, name control-plane)	Automatic	native (FALAK_LOCAL_BUILDER_MODES)	Every organization
Builder server (type builder)	Create a server of type Builder; falak-builder is installed and configured when it finishes provisioning	native, docker (with Docker)	Its organization
External builder	Settings → Builders → New builder, then run falak-builder serve anywhere	as configured	Its organization

A builder counts as online when it polled within the last 120 seconds. Managing builders needs builds.manage.

Run an external builder

1. Create the builder in Settings → Builders and copy its token (kbt_…).

2. On the machine (Linux amd64/arm64 with git and, for Docker builds, Docker with Buildx):

   curl -fsSL -o /usr/local/bin/falak-builder https://falak.example.com/install/builder/linux-amd64
   chmod +x /usr/local/bin/falak-builder
   FALAK_URL=https://falak.example.com FALAK_BUILDER_TOKEN=kbt_… FALAK_BUILDER_NAME=build-1 \
     falak-builder serve

3. Run it under systemd or another supervisor so it restarts.

Docker builds on an external builder

An external builder in Docker mode pushes images to Falak’s built-in registry at https://registry.<your domain>. Falak sends the registry address and credentials with each job, so there is nothing to log in to, but the machine must resolve and reach that host over HTTPS, and its Docker must trust the certificate (the default Let’s Encrypt one is; with --tls internal it is not). Builder servers work the same way.

falak-builder commands

falak-builder run [--job FILE|-]     run one job (JSON), stream NDJSON events to stdout
falak-builder serve                  poll the control plane for jobs (FALAK_URL + FALAK_BUILDER_TOKEN)
falak-builder detect [DIR]           print the detected build plan (--dockerfile: the generated Dockerfile)
falak-builder version

Flag	Env	Default
--url (serve)	FALAK_URL	required
--token (serve)	FALAK_BUILDER_TOKEN	required
--name (serve)	FALAK_BUILDER_NAME	hostname
--wait (serve)		30 s long-poll
--once (serve)		exit after one job
--work-dir	FALAK_BUILDER_WORK_DIR	<tmp>/falak-builder/work (base: FALAK_BUILDER_DIR)
--cache-dir	FALAK_BUILDER_CACHE_DIR	<tmp>/falak-builder/cache
--artifacts-dir	FALAK_BUILDER_ARTIFACTS_DIR	<tmp>/falak-builder/artifacts
--keep-workspace		off (debugging)
--log-level	FALAK_LOG_LEVEL	info
--runtime (detect)		hint: php, node, bun, deno, static

Caution

Two builder processes sharing one token must use different names. A poll by one would otherwise fail the other’s running build (“Builder <name> restarted during the build.”).

Limits and timeouts

Setting	Default
Build timeout	1800 s (FALAK_BUILD_TIMEOUT), plus 120 s grace
Assigned but never started	re-queued after 180 s (3 attempts)
No heartbeat from a running build	failed after 90 s (FALAK_BUILD_HEARTBEAT_TIMEOUT)
Queued with no eligible builder	failed after 3600 s (FALAK_BUILD_QUEUE_TTL)
Build log retention	30 days

Troubleshooting

Symptom	Fix
Builds stay queued	falak-ctl logs builder. Docker-mode builds need a builder that accepts docker; the host builder does native only by default.
Docker build fails at push (no such host, 401, x509)	The registry.<domain> record is missing or the install predates the registry: falak-ctl up, add the record, then falak-ctl registry status. x509: the builder doesn’t trust the registry’s certificate (--tls internal).
Build fails with railpack detected …, which native builds do not support	Use the Docker build mode for that stack.
Builder <name> restarted during the build.	The builder process restarted (for example during falak-ctl update). Redeploy.
Build is slow the first time	Caches are warm from the second build on (package manager and BuildKit caches).

Next steps

BuildsDetection and build-time variables.

Internal builder APIThe protocol builders speak.