Environment variable interpolation

rayfin.yml supports environment variable interpolation using ${VAR} / ${VAR:-default} shell-style syntax, so you can keep environment-specific values (connection strings, API keys, URLs) out of the committed config file.

Syntax

• ${VAR} — simple substitution. Fails if the variable is unset or empty.
• ${VAR:-default} — substitution with a default if the variable is unset or empty.

By convention, :- treats both an undefined variable and an empty string the same way — both fall through to the default.

# .env
DEFINED=value
EMPTY=
# UNDEFINED is not set

# rayfin.yml — results:
config1: ${DEFINED}             # → "value" (uses the variable)
config2: ${EMPTY:-fallback}     # → "fallback" (empty, uses default)
config3: ${UNDEFINED:-fallback} # → "fallback" (unset, uses default)
config4: ${DEFINED:-fallback}   # → "value" (defined, ignores default)
config5: ${EMPTY}               # → Error! (empty without default)
config6: ${UNDEFINED}           # → Error! (unset without default)

Usage

Basic substitution

services:
  data:
    dialect: ${DB_DIALECT}

DB_DIALECT=mssql

Default values

services:
  data:
    dialect: ${DB_DIALECT:-mssql}

Partial interpolation

Combine static text with a variable:

services:
  auth:
    allowedRedirectUris:
      - https://${APP_HOSTNAME}/callback

.env file location

By default, Rayfin loads variables from rayfin/.env. Override this three ways, highest priority first:

1. CLI flag:

   npx rayfin up --env-file /production.env

2. Environment variable:

   export RAYFIN_ENV_FILE='/staging.env'
   npx rayfin up

3. Default: rayfin/.env.

Resolution priority

1. Shell environment variables (if non-empty).
2. Variables from the resolved .env file (if non-empty).
3. Default values, when specified with :- syntax and the variable is unset or empty.
4. Error, if the variable is unset or empty and no default is given.

This is the same priority order used everywhere else Rayfin resolves environment values — see Environment variables for the canonical reference, including how it composes with --env-file.

Type coercion

Interpolated values are coerced to the matching YAML type only when the entire value is a single variable reference:

services:
  auth:
    expiryInMinutes: ${TOKEN_EXPIRY}   # becomes the number 60, not the string "60"
  data:
    enabled: ${DATA_ENABLED}           # becomes the boolean true, not the string "true"

TOKEN_EXPIRY=60
DATA_ENABLED=true

Partial interpolation always produces a string, even when the referenced variable looks numeric:

folder: build-${BUILD_NUMBER}  # → the string "build-42"

Security best practices

1. Never commit .env files — they hold secrets and environment-specific values. rayfin/.env is gitignored by default.
2. Provide rayfin/.env.example — document required variables for other developers with placeholder values.
3. Use shell environment variables in CI/CD — override .env with build and deployment secrets rather than checking a CI-specific .env file into the repo.
4. Omit default values for required configuration — a variable with no :- default fails fast instead of silently deploying with a wrong value.

Error handling

A missing required variable fails with a specific, actionable message rather than a silent fallback:

❌ Environment variable 'DB_HOST' referenced in rayfin.yml (services.data.host) is not defined.
   Set it in .env file or shell environment.