# Core concepts tour

> A quick tour of Falak's vocabulary — organization, project, environment, service, site, server, agent, build, deployment, release — and how they relate.

Source: https://falak.sh/docs/getting-started/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](/docs/reference/glossary/) lists them all.

## The hierarchy

```text title="How Falak organizes things"
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

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](/docs/guides/teams-and-roles/).

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

![The project canvas for the production environment: service cards for a WordPress blog, a static docs site, a Next.js marketing site, a Laravel storefront and a PostgreSQL database, with dashed arrows showing references.](./_images/canvas-board.png)

Details: [Projects, environments and services](/docs/concepts/projects-environments-services/).

## Site

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`, `docker` or `compose`;
- 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](/docs/concepts/sites-and-runtimes/).

## 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](/docs/concepts/servers-and-agents/), [Server types](/docs/servers/server-types/).

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

```text title="Deployment phases"
BUILD (once) → FETCH (all servers) → PREPARE (all) → MIGRATE (leader only)
             → ACTIVATE (all, together) → RESTART processes → HEALTH CHECK (all)
             → on any failure: ROLLBACK (all) + alert
```

Falak keeps the last 5 releases by default, so a **rollback** is instant: it points `current` back at an earlier release.

Details: [Builds](/docs/concepts/builds/), [Deployments and releases](/docs/concepts/deployments-and-releases/).

## 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](/docs/guides/domains/).

## 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](/docs/guides/processes/).

## 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](/docs/templates/deploy-a-template/).

Terms are stable across surfaces: a site in the UI is a `site` in the API (`/api/v1/sites`) and in the CLI (`falak sites list`). Sites can be addressed by id or slug everywhere.

## Next steps