# Preview environments

> A Falak preview environment for every pull request: the preview domain, project settings, database strategies, fork approval and lifecycle.

Source: https://falak.sh/docs/guides/preview-environments/

Since v0.10.0 Falak can deploy a **preview environment for every pull request** (GitHub, GitLab and Bitbucket merge or pull requests): a fork of a base environment, with its own URLs, databases and limits, torn down when the pull request closes.

## 1. Set the preview domain (operator)

Previews are served under one **preview domain** per Falak install, for example `pr-12-web.prv.example.com`. The owners and admins of the operator organization set it under **Settings → Previews**:

| Field | Meaning |
|---|---|
| Domain | For example `prv.example.com`. Only previews use names under it; sites can't add them |
| Edge server | The wildcard record points at its public address |
| DNS provider | A [Cloudflare credential](/docs/guides/cloudflare/), or **None (I keep the wildcard record)** |

- **With Cloudflare**, Falak creates `*.<domain>` pointing at the edge server and gets **one wildcard certificate** (DNS-01) for every preview there, so Let's Encrypt's per-domain limits are untouched. A preview on another server gets a DNS record and a certificate of its own.
- **Without a DNS provider**, add the wildcard record yourself. Previews then run on the edge server, and each live preview host gets its own certificate when it is routed.

The edge must be Caddy 2.8 or newer with the `caddy-dns/cloudflare` module for DNS-01 (Falak's FrankenPHP build has it). **Turn previews off** removes the domain.

The operator organization is the one `install.sh` records as `FALAK_DR_ORGANIZATION` (the only organization of a single-organization install).

## 2. Turn previews on for a project

1. Open the project's **Previews** tab → **Settings**, and turn on **Previews for pull requests**.
2. Fill in:

   | Setting | Meaning |
   |---|---|
   | Base environment | Usually staging. Previews copy its services |
   | Server | Where previews run. Default: the base environment's server |
   | Fork server | Where pull requests from **forks** run: a server with nothing but previews, never the preview edge. Default: none, forks are not previewed |
   | Variables previews copy | Names, comma separated. Secret values never copy; your own pull requests also keep `${{ }}` references |
   | Domain pattern | Under the preview domain; placeholders `{number}`, `{service}`, `{project}`. Default `pr-{number}-{service}` |
   | Access | **Basic auth** (default; credentials shown in Falak only) or **Public** |
   | Concurrent previews | Default 5. More pull requests wait until one closes |
   | Idle time to live (hours) | Default 72. Previews without a push for this long are deleted |

3. For each service of the base environment choose **Run in each preview**, **Share the base environment's**, or **Leave out**. Sharing a database means previews read and write the base environment's data: Falak asks you to confirm it.
4. For each database that runs in previews, choose its data (below).
5. Save. Enabling previews pins the repositories' webhooks so they receive pull request events.

With [config as code](/docs/guides/config-as-code/#previews), the `previews` block of `falak.yaml` holds these settings, and a preview is built from the pull request's own file (a fork's: the base branch's).

## Databases

| Data | What a preview gets |
|---|---|
| **Empty** (default) | A new, empty database; the deploy script migrates and seeds |
| **Newest backup of an environment** | The newest Falak backup of the chosen environment (default: the base) restored into the preview. Production isn't touched. Copying an **unsanitized production** backup needs the project's explicit confirmation |
| **Production, sanitized** | Production's newest backup (by default), then your **sanitize script** — SQL, or a shell command in the database container — run as the database's user before the preview starts |

Nothing deploys until every database is ready. If the sanitize script fails, the restored data is deleted and the preview never starts; a production copy not sanitized yet is dropped as soon as the preview fails, waits for an approval or closes. Redis and Valkey always start empty, volumes start empty, and preview databases never get point-in-time recovery or backup schedules.

## Secrets and limits

- Previews only get secrets marked **Available to preview environments** in the [secret store](/docs/secrets/secret-store/). A deployment that needs another one fails with a clear message.
- Preview sites always run as their own Linux user and get small [resource limits](/docs/guides/resource-limits/#defaults-per-environment) (384 MB, 0.5 CPU).

## Lifecycle

- **Opened**: Falak forks the base environment, creates the databases and volumes, deploys, then posts a comment and a commit status (`falak/preview`) with the URLs.
- **Pushed**: the preview redeploys.
- **Closed or merged**: everything is torn down — sites, databases, volumes and DNS records — and the comment is updated.

Comments and statuses are generic (ready, failed, removed); errors, server names and script output stay in Falak. The project's **Previews** tab lists every pull request with its status, URLs and basic auth credentials, with **Redeploy** and **Delete**. In the environment switcher, previews are grouped under *Previews*.

## Pull requests from forks

Fork pull requests **never deploy automatically**: their code could try to read secrets.

- A project member approves in Falak (**Approve** on the Previews tab), or comments `/falak preview` on the pull request from a provider account they connected in Falak, with `previews.manage`. A comment older than the current head approves nothing, and **every new commit needs a new approval**.
- Fork previews run only on the **fork server**, only as Docker / Compose services under the strict Compose policy, share no service with the base environment, resolve **no secrets at all**, get only empty or sanitized databases, and get the smallest limits (256 MB, 0.25 CPU).

## Cookies on a shared preview domain

All previews of an install share the preview domain, so one preview can set cookies for the whole domain that another reads. Falak's own panel uses `__Host-` cookies for that reason. Make your apps do the same — for Laravel: `SESSION_COOKIE=__Host-app_session`, `SESSION_SECURE_COOKIE=true`, and no `SESSION_DOMAIN`.

## Limits

- Not yet: cloning volumes into previews, a seed command for empty databases (the deploy script migrates), cost estimates, and Compose public services other than the primary one.
- Webhooks created before v0.10.0 don't send pull request events: re-save the site's push-to-deploy, or add the pull request events at the provider. A GitHub App created by an earlier Falak also needs the pull request, issue and commit status permissions and the `pull_request` and `issue_comment` events, which new apps get.

## Permissions

| Action | Permission | Roles |
|---|---|---|
| See previews, their URLs and access credentials | `previews.view` | owner, admin, developer, viewer |
| Configure previews, approve forks, redeploy and delete previews | `previews.manage` | owner, admin, developer |
| Set the preview domain | Owner or admin of the operator organization | |

## Next steps
