Docs / Configuration / Environment variables

Environment variables

Environment variables let you change behaviour between machines, environments and deployments without editing code or the config file.

On this page: Precedence · Variable reference · Setting variables · Troubleshooting

Precedence

When the same setting can be provided in more than one place, the first match below wins:

Command-line flags
Environment variables
The config file (config.yaml)
Built-in defaults

Variable reference

Variable names are case-sensitive and always uppercase. Boolean values accept true/false, 1/0, or yes/no.

Variable	Default	Description
`APP_ENV`	`development`	Selects the active profile. One of `development`, `staging`, `production`.
`APP_PORT`	`8080`	TCP port the server listens on.
`APP_LOG_LEVEL`	`info`	Minimum log level: `debug`, `info`, `warn`, `error`.
`APP_DATA_DIR`	`./data`	Directory used for local state and caches.
`APP_API_KEY`	none	Key used to authenticate outbound API calls. Treat as a secret.
`APP_CONFIG_FILE`	`./config.yaml`	Path to an alternate config file.
`APP_TIMEOUT_SECONDS`	`30`	Timeout applied to outbound requests.
`APP_TELEMETRY`	`true`	Set to `false` to disable anonymous usage reporting.

Setting variables

Shell (macOS, Linux)

export APP_ENV=staging
export APP_LOG_LEVEL=debug
./app serve

One-off for a single command

APP_PORT=9000 ./app serve

Windows PowerShell

$env:APP_ENV = "staging"
.\app.exe serve

.env file

If a .env file exists in the working directory, it is loaded at startup. Variables already set in the real environment are not overwritten.

# .env
APP_ENV=development
APP_LOG_LEVEL=debug
APP_DATA_DIR=./.local-data

Do not commit .env files that contain secrets. Add them to .gitignore and use your platform's secret store in production.

Troubleshooting

My variable is ignored

Check three things: the exact spelling and case of the name, that the variable is exported (not just set in the current shell session as a local variable), and that a command-line flag is not overriding it.

Print the resolved configuration

To see the final values the process will use, along with where each one came from:

./app config show --sources

Invalid value

If a value cannot be parsed, the server exits at startup with code 2 and a message naming the variable. See error codes for the full list.