Build modes

Every Git-backed site has a build mode that decides what the builder produces. Pick it under Settings → Build → Build mode.

Compare

	Native	Docker
API value	native	docker
Output	A tar.gz release unpacked into releases/<id>	An image <registry>/<namespace>/<slug>:<build-id>
Runtimes	frankenphp, php-fpm, node, bun, deno, static	docker, compose
Runs on the server as	Files served by Caddy/FrankenPHP/PHP-FPM, or a supervised process	A container (blue/green) or a Compose project
Needs	Any builder (the control plane builder works)	A builder with Docker: a builder server, or the host builder with docker enabled
Rollback	Switch current back (instant)	Start the previous image
Processes tab (workers, cron)	Yes	No
Default for	PHP, JavaScript and static presets	Docker preset

A third mode, on-server (building on the target server), exists in the data model but is not supported yet; deployments with it fail immediately with a clear error.

When to choose Docker

• Your app needs system packages that Falak’s servers do not have.
• You already maintain a Dockerfile.
• You deploy a multi-container app (Compose).

Otherwise native is faster, needs no registry, and gives you Falak-managed processes and zero-downtime symlink switches.

Enable Docker builds

The builder on the control plane host accepts only native jobs by default. You have two options:

1. Recommended: add a builder server. Create a server of type Builder with Docker. When it finishes provisioning, Falak installs falak-builder on it with its own token. It then takes Docker (and native) jobs for your organization.

2. Or let the host builder build images. Only when the host builder can reach a Docker daemon with BuildKit: set FALAK_LOCAL_BUILDER_MODES=native,docker on the control plane (in /opt/falak/custom.env), then falak-ctl up. The stock builder container has no Docker daemon, so this needs your own setup.

Builds that no builder can take stay queued and fail after FALAK_BUILD_QUEUE_TTL (3600 s).

Falak’s registry

Docker builds push to Falak’s built-in registry, which the installer sets up at https://registry.<your domain> (basic auth, credentials generated into .env). Builders push there and servers pull from it, pinned by digest; Falak hands both the credentials. Create the registry. DNS record before your first Docker build.

Variable	Default
FALAK_REGISTRY_URL	registry.<domain> (registry.falak.local in the simulation)
FALAK_REGISTRY_NAMESPACE	falak
FALAK_REGISTRY_USERNAME, FALAK_REGISTRY_PASSWORD	generated by the installer

Old images are deleted daily and their layers freed by a weekly garbage collection. See The built-in image registry.

Caution

With --tls internal, Docker on builder servers and app servers doesn’t trust the registry’s certificate. Docker builds need --tls acme, or Caddy’s internal root trusted in each Docker daemon.

Next steps

BuildsDetection, caching and build-time variables.

BuildersRun and manage builders.