Skip to content

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.

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

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

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.

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

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

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.

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