Skip to content

falak-ctl reference

falak-ctl is installed to /usr/local/bin/falak-ctl by the installer. Run it as root on the control plane host.

falak-ctl help
falak-ctl status containers, health, version, URLs, PHP thread usage
falak-ctl logs [service] [-f] recent logs (all services, or one)
falak-ctl up | down | restart [svc] start / stop / restart the stack
falak-ctl update [--version vX.Y.Z] backup -> pull -> migrate -> restart -> health check,
automatic rollback (previous version + DB restore) on failure,
then removes Falak images older than the previous version
falak-ctl prune-images [--dry-run] remove Falak images except the current and previous version
falak-ctl backup [--label NAME] [--upload] [--include-registry]
Postgres dump + app storage + Fleet CA + edge PKI + .env -> backups/
(+ the KEK, only when the DR passphrase encrypts the backup);
--upload: to the DR bucket (encrypted only), failing when it can't
falak-ctl restore <file | s3://latest | s3://NAME> [--yes] [--force]
restore a backup (stops the app while restoring); s3:// downloads an
authenticated backup (.fdr) and checks it with the DR passphrase first
falak-ctl dr setup [options] disaster recovery: DR bucket, passphrase, backup + drill timers
falak-ctl dr status [--json] last backup, its age and size, last drill, configured or not
falak-ctl dr drill [--local] restore the latest backup into a throwaway stack (falak-drill), check it
falak-ctl doctor DNS, certificates, ports, disk, containers, agent API, PHP threads, KEK
falak-ctl kek init | status key-encryption key (secrets/kek): create if missing, fix permissions / check
falak-ctl kek export <file> write the emergency kit (the KEK) to a file you keep offline
falak-ctl kek import <file> [--force] put the KEK back from an emergency kit
falak-ctl kek rotate new KEK; data keys are re-wrapped, the old KEK stays for older backups
falak-ctl domain set <domain> [--keep-old] move the panel to a new domain
falak-ctl registry status | prune [--dry-run] | gc [--dry-run] [--force]
built-in image registry: address and size / delete unneeded images /
garbage-collect (weekly from /etc/cron.d/falak-registry-gc)
falak-ctl panel-access tailnet | public | status
close the panel to browsers outside your Tailscale tailnet / reopen it / show
falak-ctl admin reset-password <email> [--password=...]
falak-ctl admin create <email>
falak-ctl artisan <args...> run php artisan in the control-plane container
falak-ctl compose <args...> raw docker compose with the install's settings
falak-ctl reload-configs recreate services whose mounted config files changed on disk
falak-ctl version
Variable Default Meaning
FALAK_DIR /opt/falak Install directory
FALAK_PROJECT falak Compose project name
FALAK_LOG_TAIL 200 Lines shown by logs

Settings are read from $FALAK_DIR/.env; the DR bucket and passphrase from $FALAK_DIR/dr/dr.env. backup, restore, update and dr drill run one at a time: a second one waits (timers) or stops with a message.

Version, install directory, each service’s status and image, the panel/agent API/Grafana URLs, PHP thread usage and the last backup:

==> Falak v0.2.6 at /opt/falak (project falak)
SERVICE STATUS IMAGE
control-plane Up 2 hours (healthy) ghcr.io/falak-sh/falak-control-plane:v0.2.6
…
panel: https://falak.example.com
agent API: https://agents.falak.example.com/agent/v1
PHP threads: panel 1/8 busy · agent-api 5/128 busy
last backup: /opt/falak/backups/falak-backup-20260928T031500Z.tar.gz

docker compose logs --tail=200 for all services or one (control-plane, agent-api, horizon, reverb, scheduler, postgres, valkey, edge, builder, and the observability services). -f/--follow streams.

Checks, in order: DNS (public IPs and every Falak hostname, including registry.), Ports, Containers, Certificates (warns when one expires within 14 days), Agent API (must answer 401 without a client certificate), Image registry (401 without credentials, 200 with them), PHP threads (flags a pool at 80 % or saturated, and the 0.2.x FRANKENPHP_CONFIG hotfix line), Disk & memory, Backups, the KEK (present, readable, unwrapping the database’s data keys) and whether disaster recovery is configured.

  • up [timeout]: start/converge the stack, wait until healthy (default 420 s), recreate services whose mounted config files changed, then health-check.
  • down: stop the stack (volumes are kept).
  • restart [service]: restart all services or one.

Updates to the latest release or a given tag, with an automatic backup and rollback. Alias: upgrade. --skip-backup skips the pre-update backup (then there is nothing to roll back to). After a successful update it records the version it came from as FALAK_PREVIOUS_VERSION in .env and removes older Falak images (see prune-images). See Upgrade.

Removes every tag of the falak-control-plane, falak-edge and falak-builder images except the current version (FALAK_VERSION) and the previous one (FALAK_PREVIOUS_VERSION, the rollback target). --dry-run lists what it would remove.

  • Third-party images (Postgres, Valkey, Grafana, …), images still used by a container and volumes are never touched.
  • update runs this automatically. Set FALAK_PRUNE_IMAGES=0 in .env to keep every image.
  • With FALAK_PULL=0 (images built locally, e.g. --build-from-source), update never prunes, because removed images could not be pulled again. prune-images still works there and warns first.
$ sudo falak-ctl prune-images --dry-run
would remove ghcr.io/falak-sh/falak-control-plane:v0.4.2
…

Operates the built-in image registry that Docker builds push to.

  • registry status: the registry’s address, whether it runs, how much it stores, and whether it answers with its credentials. On an install from before the registry it also adds the missing FALAK_REGISTRY_* settings.
  • registry prune [--dry-run]: deletes the images of builds whose artifact was pruned, never one a pending, live or rollback release needs. The control plane runs it daily at 03:45 (falak:registry-prune).
  • registry gc [--dry-run] [--force]: garbage-collects layers and untagged manifests nothing references, which frees the disk space. The registry is stopped while it runs. It is skipped while an image build is queued or running (or when the control plane can’t tell); --force runs it anyway.

falak-ctl up and update write a weekly cron entry, /etc/cron.d/falak-registry-gc (Sunday 04:17, log in /var/log/falak-registry-gc.log). Set FALAK_REGISTRY_GC=0 in .env to remove it.

$ sudo falak-ctl registry status
address: https://registry.falak.example.com (user falak; password: FALAK_REGISTRY_PASSWORD in /opt/falak/.env)
✓ registry running, 1.2G stored
✓ https://registry.falak.example.com/v2/ answers with the credentials (200)

backup [--label NAME] [--upload] [--include-registry]

Section titled “backup [--label NAME] [--upload] [--include-registry]”

Writes /opt/falak/backups/falak-backup-<UTC timestamp>[-label].fdr, encrypted and authenticated with the DR passphrase (a plain .tar.gz without one, which leaves the KEK out). --upload also sends it to the DR bucket and fails when it can’t; unencrypted backups are never uploaded. See Backup and restore.

restore <file | s3://latest | s3://NAME> [--yes] [--keep-env] [--force]

Section titled “restore <file | s3://latest | s3://NAME> [--yes] [--keep-env] [--force]”

Restores a backup: a path, a file name inside backups/, or an upload from the DR bucket (authenticated with the DR passphrase before anything is decrypted). Asks for confirmation unless --yes; non-interactive runs require --yes. It refuses a backup made by a newer Falak, or one whose KEK this host lacks, unless --force. --keep-env keeps this host’s .env and custom.env instead of the backup’s.

  • dr setup: asks for an S3-compatible bucket and a DR passphrase (or takes --endpoint, --bucket, --region, --prefix, --access-key, --secret-key-file, --passphrase-file, --every HOURS, --drill monthly|off, --include-registry), tests the bucket, writes /opt/falak/dr/dr.env and installs falak-backup.timer and falak-drill.timer.
  • dr status [--json]: the last backup, its age and size, the last drill, and whether DR is configured.
  • dr drill [--local] [--backup FILE]: restores the latest upload (or a local backup) into a throwaway Compose project and checks it.

See Disaster recovery.

kek init | status | export | import | rotate

Section titled “kek init | status | export | import | rotate”

The key-encryption key that seals every secret.

  • kek init creates a missing KEK (never replaces one) and fixes its permissions; kek status checks it.
  • kek export <file> writes the emergency kit; it is never printed to the terminal. Move the file off the host.
  • kek import <file> [--force] puts the KEK back; --force replaces a different one, which is kept aside.
  • kek rotate creates a new KEK, keeps the old one as secrets/kek.previous and re-wraps every data key. Export the kit again afterwards.

Moves the panel to a new domain. See Change the domain.

Closes the panel to everyone outside your Tailscale tailnet, reopens it, or shows the current setting. tailnet refuses unless this machine is on the tailnet (tailscale ip -4 works) and its route is approved. Set it in FALAK_PANEL_ALLOW in .env; the edge is recreated. Details and the paths that stay public: Tailscale.

admin reset-password <email> [--password=…]

Section titled “admin reset-password <email> [--password=…]”

Sets a new password (generated and printed when --password is omitted).

admin create <email> [--organization=…] [--token=NAME] [--name=…] [--password=…] [--json]

Section titled “admin create <email> [--organization=…] [--token=NAME] [--name=…] [--password=…] [--json]”

Creates a user with an organization; --token also issues a full-access API token and prints it. Runs php artisan falak:admin.

php artisan in the control-plane container. Useful commands:

Command Purpose
falak:agents [--outdated] [--count] Shipped agent build and outdated agents
falak:admin <email> … Create or reset admins
telemetry:grafana:provision [--organization=…] Re-provision Grafana
templates:render <slug> [--domain=…] [--env-file=…] Render a catalog template
projects:backfill [--organization=…] Place orphan sites/databases into Default projects

Raw docker compose with the install’s project, env file and profiles, for example falak-ctl compose ps -a.

Recreates services whose mounted config files changed on disk (loki.yaml, tempo.yaml, the gateway Caddyfile, Grafana provisioning and dashboards). It compares what each running container sees at its Falak mounts with the files on disk:

==> mounted config files changed: recreating loki
✓ recreated loki

The same check runs on up, after a restore, during updates and rollbacks. Run it after editing files under /opt/falak/observability/ by hand (such edits are replaced by the next update).

Prints FALAK_VERSION.