Skip to content

Environment variables

Every site has an encrypted set of environment variables. Falak writes them into each release’s .env and into the environment of the site’s processes. This page shows how to edit them and when changes take effect. For API keys and passwords shared between services, use the secret store and reference them with ${{ secrets.NAME }}.

  1. Open the site’s panel → Variables.
  2. Add a row with New variable, or switch to the Raw editor to paste a whole dotenv file (you see a diff before saving).
  3. Save. A bar reminds you that changes apply on the next deploy.
  4. Click Deploy.

Values are masked. Revealing a value is recorded in the audit log.

Each save creates a new version of the environment. The API returns it:

GET /api/v1/sites/shop/env
{"data": {"content": "APP_ENV=production\nAPP_KEY=base64:…\n", "version": 3}}

You do not set these; every release gets them:

Variable Value
FALAK_SITE_ID, FALAK_SERVER_ID, FALAK_DEPLOYMENT_ID, FALAK_RELEASE_ID Upper-case ULIDs
FALAK_SITE The site slug (process environments)
PORT, HOST The app port and 127.0.0.1 (Node, Bun, Deno web processes; PORT for Docker)
NODE_ENV production for JavaScript web processes unless you set it

Presets add initial variables when a site is created (for example APP_KEY for Laravel); after that they are yours to edit.

Values can reference another service in the same environment:

DATABASE_URL=${{ shop-db.DATABASE_URL }}
REDIS_HOST=${{ cache.REDIS_HOST }}

See Variable references.

Reference a secret from the secret store instead of pasting its value:

STRIPE_SECRET=${{ secrets.STRIPE_SECRET }}

An existing variable can be moved into the store with Promote a variable to a secret on the Secrets page.

  • Classic sites: the .env is on a tmpfs (/run/falak/env/<site>.env, mode 0440); shared/.env and the release’s .env are symlinks to it. After a reboot the agent asks for it again, so variables never reach persistent disk.
  • Docker sites: environment variables by default, or secret variables as files in /run/secrets (Settings → Deploy → Secrets).
  • Output masking: values of secret variables (secret references, and names like *PASSWORD*, *TOKEN*, *_KEY, DATABASE_URL) are shown as •••• in deploy, hook and build output.

Builds only see:

  • variables starting with VITE_, NEXT_PUBLIC_, NUXT_PUBLIC_, PUBLIC_ or REACT_APP_;
  • variables marked Expose to deploy script.

Expose to deploy script is a per-variable switch. Exposed variables are also exported into your deploy script sections, so you can use them in custom steps.

Two variables change the build itself: FALAK_INSTALL_COMMAND and FALAK_BUILD_COMMAND. See Monorepos and build commands.

Terminal window
falak env pull shop > .env.production # to stdout
falak env pull shop --file .env.production # written with mode 0600
falak env push shop --file .env.production # replaces ALL variables
falak env push shop < .env.production # same, from stdin
falak deploy shop --wait # apply

push refuses an empty file. It replaces the whole environment, so always pull, edit and push the complete file. Keys that were exposed to the deploy script stay exposed.

Terminal window
curl -X PUT https://falak.example.com/api/v1/sites/shop/env \
-H "Authorization: Bearer $FALAK_TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" \
-d '{"content": "APP_ENV=production\nAPP_DEBUG=false\n"}'
Response
{"data": {"version": 4, "changed": true, "keys": ["APP_ENV", "APP_DEBUG"]}}

422 with errors.content when the dotenv cannot be parsed. See Sites API.

Action Permission Roles
Reveal / read variables sites.env.view owner, admin, developer
Edit variables sites.env.manage owner, admin, developer

Viewers cannot read variable values.

  • Up to 500 variables when creating a site through the API; each value up to 64 KiB.
  • Edit variables in Falak, not in .env on a server: the file is on a tmpfs that Falak writes on every deploy and after a reboot, and hand edits on one server do not reach the others.