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.
DATABASE_URL=${{ shop-db.DATABASE_URL }}API_BASE_URL=https://${{ api.APP_DOMAIN }}/v1MAIL_FROM=${{ shared-config.MAIL_FROM }}Syntax
Section titled “Syntax”${{ service.KEY }}— whitespace inside the braces is allowed.serviceis the service name on the canvas. It matches case-insensitively, and spaces, dots and underscores count as dashes: a service namedShop DBorshop_dbisshop-db.KEYis a variable of that service.- References can be embedded in longer values, as
API_BASE_URLshows.
What a service exposes
Section titled “What a service exposes”| 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.1and 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
Section titled “Secrets”${{ 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.
When references resolve
Section titled “When references resolve”At deploy time, in three places:
- the release’s
.envand the processes’ environment; - the deploy script’s environment;
- 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.
Errors
Section titled “Errors”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:
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.
On the canvas
Section titled “On the canvas”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.
Templates and Compose
Section titled “Templates and Compose”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.