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 registry status                built-in image registry: address, size, answers with its credentials
falak-ctl registry prune [--dry-run]     delete registry images no build or release needs (also daily)
falak-ctl registry gc [--dry-run] [--force]  delete layers no image references (stops the registry briefly; weekly from cron)
falak-ctl backup [--label NAME]          Postgres dump + app storage + Fleet CA + .env -> backups/
falak-ctl restore <file> [--yes]         restore a backup (stops the app while restoring)
falak-ctl doctor                         DNS, certificates, ports, disk, containers, agent API, PHP threads
falak-ctl domain set <domain> [--keep-old]   move the panel to a new domain
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

Environment

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.

status

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/othmanhaba/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

logs [service] [-f]

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.

doctor

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, and Backups.

up, down, restart [service]

• 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.

update [--version vX.Y.Z]

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.

prune-images [--dry-run]

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/othmanhaba/falak-control-plane:v0.4.2
  …

registry status | prune | gc

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] [--quiet]

Writes /opt/falak/backups/falak-backup-<UTC timestamp>[-label].tar.gz (or .tar.gz.enc with a passphrase). See Backup and restore.

restore <file> [--yes] [--keep-env]

Restores a backup (a path, or a file name inside backups/). Asks for confirmation unless --yes; non-interactive runs require --yes. --keep-env keeps the current .env instead of the backup’s.

Danger

A restore replaces the database, app storage, Fleet CA and .env.

domain set <new-domain> [--keep-old]

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

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]

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

artisan <args…>

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

compose <args…>

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

reload-configs

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).

version

Prints FALAK_VERSION.