Provisioning
After the agent enrolls, Falak first runs the machine check: it looks at the software already on the server and decides per component to install it, use what is there, or stop with a fix. Then the control plane sends one declarative provisioning plan (provision.apply) built from the server’s type and software choices. The agent applies it step by step, skipping what is already in place. Re-provisioning (server page → Re-provision) sends the same plan again and is safe.
The plan, step by step
Section titled “The plan, step by step”| Step | What happens |
|---|---|
| hostname | Set from the server name, lower-cased to an RFC 1123 name (for example App 1 → app-1). Servers you connect yourself keep their hostname. |
| timezone | The server’s timezone (default UTC) |
| swap | A swap file: 2 GB on machines under 2 GB RAM, 4 GB under 8 GB, none from 8 GB. (Skipped inside containers, and when the machine already has swap.) |
| apt | Base packages plus Docker (below), except components the machine check found already installed |
| user:falak | The falak user: shell /bin/bash, home /home/falak, groups www-data and docker, no sudo |
| php:<version> | Each chosen PHP version with the standard extensions; PHP-FPM when the runtime is PHP-FPM; the default version becomes php on the CLI |
| frankenphp | FrankenPHP 1.9.1 as the server’s edge (embeds Caddy), SHA-256 verified; it joins the sites’ groups |
| node:<version> | Node.js from nodejs.org, checksum verified |
| caddy | Standalone Caddy (from the official Caddy apt repository) on servers that serve HTTP without FrankenPHP: PHP-FPM servers and load balancers |
| service:<name> | fail2ban and Docker, enabled and started; Docker’s daemon.json gets "live-restore": true |
| unattended_upgrades | Security updates on, automatic reboot off (reboot time 04:00 if you enable it) |
| ssh | Hardened sshd configuration (below), verified before reload so you are not locked out |
Afterwards the default firewall rules are applied (SSH; plus HTTP/HTTPS on app, web and lb servers). The whole plan may take up to 30 minutes (provision_timeout 1800 s). Transient download failures are retried with backoff.
Packages
Section titled “Packages”Base packages on every server:
acl ca-certificates curl fail2ban git htop jq rsync sqlite3 unattended-upgrades unzip zip| Component | Packages | Service |
|---|---|---|
| Docker (every server) | docker-ce, docker-ce-cli, containerd.io, docker-buildx-plugin, docker-compose-plugin from Docker’s apt repository |
docker |
Docker must be at least version 28. The agent adds Docker’s repository (checking its key’s fingerprint) and replaces an older Docker; it falls back to the distribution’s docker.io only where Docker’s repository has no suite yet and that version is recent enough. A recent enough Docker the machine check found is used as it is.
Databases are not installed on servers. Since v0.10.0 every database runs as a container of a Falak image, so any server can run one. live-restore keeps those containers running while Docker restarts or upgrades; an explicit "live-restore": false in daemon.json is left as it is (with a warning).
- Versions offered: 8.1, 8.2, 8.3, 8.4 (default), 8.5.
- Extensions installed for every version:
bcmath,cli,curl,gd,igbinary,intl,mbstring,mysql,pgsql,readline,redis,soap,sqlite3,xml,zip. - Add or remove versions and change the default on the server page under PHP. Edit
php.inisettings there too.
SSH configuration
Section titled “SSH configuration”Falak writes this sshd configuration:
Port 22PermitRootLogin prohibit-passwordPasswordAuthentication noKbdInteractiveAuthentication noPubkeyAuthentication yesX11Forwarding noMaxAuthTries 4Runtimes installed later
Section titled “Runtimes installed later”Some runtimes are installed when a site first needs them, not during provisioning:
- Bun 1.4.2 and Deno 2.9.7, when a Bun or Deno site targets the server;
- a PHP-FPM pool and the site user, when a site is added to the server.
While that happens, the site’s target is “preparing” and deployments wait for it.
Download mirrors
Section titled “Download mirrors”Servers download FrankenPHP, Node.js, Bun and Deno from GitHub and nodejs.org. Point them at your own HTTPS mirror with FALAK_FRANKENPHP_MIRROR, FALAK_NODE_MIRROR, FALAK_BUN_MIRROR, FALAK_DENO_MIRROR. See Configuration.
Version pins (operators)
Section titled “Version pins (operators)”| Variable | Default |
|---|---|
FALAK_FRANKENPHP_VERSION |
1.9.1 |
FALAK_FRANKENPHP_SHA256 |
unset (verified against the release otherwise) |
FALAK_NODE_20 / FALAK_NODE_22 / FALAK_NODE_24 |
20.19.5 / 22.20.0 / 24.9.0 |
FALAK_BUN_VERSION |
1.4.2 |
FALAK_DENO_VERSION |
2.9.7 |