Configuration

Canonical reference: cyoda help config

This page is the narrative; the binary is authoritative.

cyoda-go reads configuration from CYODA_* environment variables and from .env-format files. The authoritative key list — every variable, its type, its default — lives in the binary. This page covers the model: how sources compose, how profiles work, and how secrets are mounted from files.

Sources and precedence

Values resolve in this order, highest to lowest:

1. Shell environment
2. .env.{profile} files (in CYODA_PROFILES declaration order; later profiles override earlier ones within their group)
3. .env in the project directory
4. User config file
5. System config file
6. Hardcoded defaults

Format is .env only (godotenv-parsed). No TOML, no YAML, no --config flag. Subcommand flags (e.g. cyoda init --force) are operation-scoped and do not override server-runtime configuration.

User config path varies by OS: ~/.config/cyoda/cyoda.env (Linux, macOS with XDG), %AppData%\cyoda\cyoda.env (Windows). System config lives at /etc/cyoda/cyoda.env on POSIX.

Profiles

CYODA_PROFILES is comma-separated and evaluated in declaration order. Within a profile, regular .env precedence applies; across profiles, later entries in the list override earlier ones.

Secrets via _FILE suffix

Any variable that accepts a credential (Postgres URL, JWT signing key, metrics bearer, gossip HMAC, bootstrap client secret) accepts a companion *_FILE variable that reads from a mounted file. Trailing whitespace is stripped. The _FILE variant takes precedence when both are set — the pattern designed for Kubernetes Secrets and Docker secrets mounts.

Related topics

• cyoda help config — cyoda configuration reference
  Environment variables beat default values. The `_FILE` suffix variant takes precedence over the plain variable when both are set — for example, `CYODA_POSTGRES_URL_FILE=/etc/secrets/db-url` wins over `CYODA_POSTGRES_URL`. There are no command-line flags for configuration values; env vars are the sole configuration surface.
• cyoda help config auth — auth configuration
  config.auth — IAM mode, JWT issuer, HMAC secret, and admin bootstrap controls.
• cyoda help config database — database configuration
  config.database — storage backend selection and per-backend connection settings.
• cyoda help config grpc — grpc configuration
  config.grpc — gRPC listener settings and compute-node credentials.
• cyoda help config schema — schema configuration
  config.schema — schema-extension log tuning.