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)
Section titled “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, 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
Section titled “2. Turn previews on for a project”-
Open the project’s Previews tab → Settings, and turn on Previews for pull requests.
-
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 ${{ }}referencesDomain pattern Under the preview domain; placeholders {number},{service},{project}. Defaultpr-{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 -
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.
-
For each database that runs in previews, choose its data (below).
-
Save. Enabling previews pins the repositories’ webhooks so they receive pull request events.
With config as code, 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
Section titled “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
Section titled “Secrets and limits”- Previews only get secrets marked Available to preview environments in the 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 (384 MB, 0.5 CPU).
Lifecycle
Section titled “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
Section titled “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 previewon the pull request from a provider account they connected in Falak, withpreviews.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
Section titled “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
Section titled “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_requestandissue_commentevents, which new apps get.
Permissions
Section titled “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 |