Skip to content

Variable references

A variable reference lets one service use another service’s variable without copying secrets around. Write ${{ <service>.<KEY> }} in a site variable; Falak replaces it with the current value when it deploys.

Site variables of 'web'
DATABASE_URL=${{ shop-db.DATABASE_URL }}
API_BASE_URL=https://${{ api.APP_DOMAIN }}/v1
MAIL_FROM=${{ shared-config.MAIL_FROM }}
  • ${{ service.KEY }} — whitespace inside the braces is allowed.
  • service is the service name on the canvas. It matches case-insensitively, and spaces, dots and underscores count as dashes: a service named Shop DB or shop_db is shop-db.
  • KEY is a variable of that service.
  • References can be embedded in longer values, as API_BASE_URL shows.
Service kind Keys
Site All of its own variables (resolved themselves)
Database (PostgreSQL, MySQL, MariaDB) DATABASE_URL, DB_CONNECTION, DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, DB_PASSWORD
Database (Redis, Valkey) REDIS_URL, REDIS_HOST, REDIS_PORT, REDIS_PASSWORD, REDIS_CLIENT

For databases:

Key Value
DB_CONNECTION pgsql, mysql or mariadb (Laravel driver names)
DB_HOST, DB_PORT The database container’s host and port for this site (below)
DB_DATABASE The database name
DB_USERNAME, DB_PASSWORD The oldest user granted access to the database (users with all privileges first)
DATABASE_URL postgresql://user:pass@host:port/db or mysql://user:pass@host:port/db (URL-encoded)

For Redis and Valkey instances:

Key Value
REDIS_URL redis://default:<password>@host:port (rediss:// when the instance requires TLS)
REDIS_HOST, REDIS_PORT The instance’s host and port for this site (below)
REDIS_PASSWORD The default user’s password
REDIS_CLIENT phpredis

Every database is a container. The host and port depend on where the site runs:

  • a container on the database’s server (Docker site, Compose stack, function) gets falak-db-<id> and the engine’s port, on the environment’s private Docker network;
  • a native site on that server gets 127.0.0.1 and the container’s host port;
  • a site on another server of the environment gets the database server’s address on a private network both share — a Falak WireGuard private network first, else the provider’s private network (DigitalOcean or Lightsail servers created with the same provider credential in the same region) — and the host port, once that address is published.

${{ secrets.NAME }} reads the secret store instead of a service (secrets is never a service name). It resolves to the current version of the nearest secret NAME of the service owning the variable: its service, environment, project, then organization secrets. A missing secret fails the deployment.

STRIPE_SECRET=${{ secrets.STRIPE_SECRET }}

References resolve against services in the same environment of the same project. After you duplicate production into staging, the same ${{ shop-db.DATABASE_URL }} points at staging’s shop-db.

At deploy time, in three places:

  1. the release’s .env and the processes’ environment;
  2. the deploy script’s environment;
  3. public build variables (those the build can see).

The resolved values are stored with the release, so a rollback uses the values that release was deployed with.

A reference to an unknown service or key, or a cycle (a references b which references a), fails the deployment before anything changes on your servers:

Example deployment errors
Unresolved variable references: DATABASE_URL: unknown service "shopdb" in ${{ shopdb.DATABASE_URL }}.
Unresolved variable references: DB_PASS: service "shop-db" has no variable PASSWORD (it exposes DB_CONNECTION, DB_HOST, …).
Unresolved variable references: A: reference cycle … .
Unresolved variable references: DB_HOST: … shares no private network with <server> … Add both servers to a private network (Network → Private networks).
Unresolved variable references: DB_HOST: … is not published on <address> yet …
STRIPE_KEY: secret STRIPE_KEY is not defined for this service …

Fix the variable and deploy again.

Every reference draws a dashed arrow from the site to the referenced service. In the Variables tab, a reference links to its service; clicking it opens that service’s panel on top.

Template inputs can default to references, for example ${{ postgres.DATABASE_URL }}, and Compose sites get the resolved values in their project .env. See Custom templates.