Core concepts tour
Falak uses a small vocabulary consistently across the UI, API, CLI and these docs. Read this page once and the rest of the documentation will make sense. Each term links to its detailed page, and the glossary lists them all.
The hierarchy
Section titled “The hierarchy”Organization (members, roles, API tokens, git connections, servers)└── Project e.g. "Shop" └── Environment e.g. "production", "staging" └── Service a card on the canvas ├── Site your app: Git repo, Docker image, Compose file or template └── Database a PostgreSQL / MySQL / MariaDB database on a server
Servers (belong to the organization; sites and databases are placed on them)Organization
Section titled “Organization”Everything belongs to an organization. Members have a role — owner, admin, developer or viewer — that decides what they can do. API tokens are pinned to one organization. See Teams and roles.
Project, environment, service
Section titled “Project, environment, service”A project groups the services of one product. Each project has one or more environments; every project starts with production. An environment is drawn as a canvas: a board of services, each shown as a card with its live status.
A service is either a site or a database. Services in the same environment can reference each other’s variables, for example DATABASE_URL=${{ shop-db.DATABASE_URL }}. Falak draws an arrow for every reference.
Details: Projects, environments and services.
A site is a deployable app. It has:
- a framework preset (Laravel, Symfony, Statamic, WordPress, PHP, Next.js, Nuxt, Node, static, Docker) that fills in sensible defaults;
- a runtime — how it runs on the server:
frankenphp,php-fpm,node,bun,deno,static,dockerorcompose; - a source: a Git repository and branch, a Docker image, or a Compose file;
- environment variables, stored encrypted and written to each release’s
.env; - one or more servers. The first is the leader, where migrations run.
Details: Sites and runtimes.
Server and agent
Section titled “Server and agent”A server is a Linux machine Falak manages. Each server has a type — app, web, db, cache, worker, lb or builder — that decides what gets installed. The agent (falak-agent) is a small program on the server that dials out to the control plane over mutual TLS, receives commands, and reports heartbeats every 15 seconds.
Details: Servers and agents, Server types.
Build, deployment, release
Section titled “Build, deployment, release”A deployment takes a commit to your servers. It starts with a build, which runs once on a builder (never on your app servers) and produces an artifact (a tarball) or a Docker image. Each server then gets a release: a directory /srv/falak/sites/<site>/releases/<release-id> with your built code. Activation points the current symlink at the new release on every server at once.
BUILD (once) → FETCH (all servers) → PREPARE (all) → MIGRATE (leader only) → ACTIVATE (all, together) → RESTART processes → HEALTH CHECK (all) → on any failure: ROLLBACK (all) + alertFalak keeps the last 5 releases by default, so a rollback is instant: it points current back at an earlier release.
Details: Builds, Deployments and releases.
Domains
Section titled “Domains”Every site with a public endpoint gets a domain: a generated one (<slug>.<server-ip-with-dashes>.sslip.io, works immediately), a test domain (<slug>.<your wildcard domain>), or a custom domain you own. Falak issues Let’s Encrypt certificates automatically. See Domains.
Processes
Section titled “Processes”Long-running programs next to your web process — queue workers, Horizon, Octane, daemons — and scheduled jobs (cron) are supervised by the agent. They start after the first deployment and restart on every deploy. See Processes.
Templates
Section titled “Templates”A template is a ready-made Docker Compose app (n8n, Plausible, Ghost, …) with inputs, generated secrets and public services. Deploying one creates a Compose site. See Templates.