Environments and configuration

Rayfin tooling reads and writes configuration through a small set of files and a handful of variable prefixes. This page covers the concepts you need while deploying — where each kind of value lives, what it's for, and how rayfin.yml pulls values in from the environment. For the complete, exhaustive variable-by-variable table, see Environment variables.

File locations

Frontend-visible variables (RAYFIN_PUBLIC_*)

Variables prefixed RAYFIN_PUBLIC_ live in rayfin/.env and are the only variables exposed to frontend builds. rayfin up populates most of these after a deploy; rayfin env (run automatically by the scaffolded predev/prebuild scripts) maps them into a framework-specific .env.local.

For Vite, RAYFIN_PUBLIC_API_URL becomes VITE_RAYFIN_API_URL, RAYFIN_PUBLIC_PUBLISHABLE_KEY becomes VITE_RAYFIN_PUBLISHABLE_KEY, and so on — a custom RAYFIN_PUBLIC_FOO becomes VITE_RAYFIN_FOO (Next.js: NEXT_PUBLIC_RAYFIN_FOO; plain: FOO). See Environment variables for the full per-framework mapping table, and rayfin env for the command that generates .env.local.

Tooling overrides

These configure CLI behavior and are never exposed to the frontend. Set them in rayfin/.env or as shell variables.

Service configuration flags

Written to rayfin/.env based on your rayfin.yml settings, and read by the Rayfin WebService:

Shell-only variables

Read from the shell environment only — never written to a file. These are the ones you'll use most often around deployment and CI/CD:

Resolution priority

When the same variable is set in more than one place, Rayfin resolves it in this order (highest priority first):

1. Shell environment variable.
2. --env-file <path> CLI flag (or RAYFIN_ENV_FILE).
3. rayfin/.env file.
4. Default value (hardcoded, or from rayfin.yml interpolation).

Variable interpolation in rayfin.yml

rayfin.yml supports shell-style variable interpolation, so you can keep environment-specific values (connection strings, API keys, URLs) out of the checked-in config.

services:
  data:
    host: ${DB_HOST}
    port: ${DB_PORT:-1433}

• ${VAR} — substitutes the variable. Fails with a clear error if it is unset or empty.
• ${VAR:-default} — substitutes the variable, or default if it is unset or empty (an empty string counts as unset).

DEFINED=value
EMPTY=
# UNDEFINED is not set

config1: ${DEFINED}             # → "value"
config2: ${EMPTY:-fallback}     # → "fallback" (empty, uses default)
config3: ${UNDEFINED:-fallback} # → "fallback" (unset, uses default)
config5: ${EMPTY}               # → Error! (empty without default)
config6: ${UNDEFINED}           # → Error! (unset without default)

When a value is entirely a variable reference, Rayfin coerces it to the matching YAML type — port: ${DB_PORT} with DB_PORT=1433 in .env becomes the number 1433, not the string "1433". Partial interpolation (http://localhost:${PORT}) always produces a string.

.env values are resolved with the same priority as everything else: shell environment first, then the .env file, then the :- default.

See Environment variable interpolation for the full syntax reference, including error handling details.