Configuration

+++ title = "Configuration" description = "Exhaustive reference for every YAML key in a Loco app's config file: loading precedence, environment resolution, and every sub-config struct." date = 2021-05-01T18:10:00+00:00 updated = 2021-05-01T18:10:00+00:00 draft = false weight = 1 sort_by = "weight" template = "docs/page.html"

[extra] lead = "" toc = true top = false +++

This page is a dictionary of every key Loco's configuration loader understands. It documents struct Config (src/config/mod.rs) and its sub-structs (src/config/{auth,server,database,logger,mailer,queue,cache}.rs). For a narrative walkthrough of settings and environments, see the-app/your-project.

Loading & precedence

• Default config folder: config/ (Config::new, src/config/mod.rs:128-131). Override with the LOCO_CONFIG_FOLDER env var (read by Environment::load, src/environment.rs:59-64).

• Config::from_folder(env, path) (src/config/mod.rs:153-174) resolves the file to load with this precedence — first file that exists wins:

  1. {path}/{env}.local.yaml
  2. {path}/{env}.yaml

  If neither exists, loading fails with Error::Message("no configuration file found in folder: ...").

• Before parsing, the entire YAML file is rendered as a template (Config::load_yaml_value, src/config/mod.rs:211-217; src/config/template.rs). Config files use the YAML-safe <%= expr %> / <% stmt %> / <%# comment %> delimiters — < is not a YAML indicator character, so a templated value like port: <%= get_env(name="PORT", default="5150") %> is still valid, unmangled YAML before it's ever rendered. Under the hood these are translated into Tera's native {{ }}/{% %}/{# #} delimiters and rendered via Tera::one_off(.., autoescape=false) (src/tera.rs). get_env(name=.., default=..), used throughout the shipped config files, is Tera's own built-in function — it is not a Loco-registered function. Tera's native {{ }}/{% %} delimiters still render for backward compatibility, but they are deprecated (they are YAML flow-mapping syntax, not a plain scalar, so a YAML formatter can rewrite and break them — see The configuration model) and log a warning when used.

• Parse failures raise Error::YAMLFile(err, path) (src/config/mod.rs:172-173).

• Config implements Display by dumping itself back to YAML (src/config/mod.rs:191-196).

• Config::get_jwt_config(&self) -> Result<&JWT> (src/config/mod.rs:180-188) returns an error if auth or auth.jwt is absent.

Environment resolution

environment::resolve_from_env() (src/environment.rs:32-38) picks the active environment name with this precedence:

1. LOCO_ENV
2. RAILS_ENV
3. NODE_ENV
4. fallback: "development" (DEFAULT_ENVIRONMENT, src/environment.rs:21)

Top-level Config

struct Config — src/config/mod.rs:62-92. Every field is a top-level YAML key.

auth

struct Auth — src/config/auth.rs:13-17.

auth:
  jwt:
    location:              # optional, default: Bearer
      from: Bearer          # or: {from: Query, name: <string>} / {from: Cookie, name: <string>}
    secret: <base64 secret> # required — must be valid base64
    expiration: 604800      # required, u64 seconds (e.g. 7 days)

JWTLocationConfig (#[serde(untagged)], auth.rs:47-54) accepts either form:

• Single(JWTLocation) — a single location map
• Multiple(Vec<JWTLocation>) — a YAML list of location maps, tried in order until one yields a token

JWTLocation (#[serde(tag = "from")], auth.rs:35-44):

Related, not YAML-configurable: default signing algorithm is HS512 (JWT_ALGORITHM, src/auth/jwt.rs:13), overridable in code via JWT::algorithm(..) (jwt.rs:51), not via config.

server

struct Server — src/config/server.rs:29-45.

server:
  binding: localhost     # optional, default "localhost"
  port: 5150             # required
  host: http://localhost # required
  ident: <string>        # optional — overrides the `Server` response header
  middlewares: {}        # optional, default {} — see the middleware catalog reference

Server::full_url() -> String returns "{host}:{port}" (server.rs:52-55).

workers

struct Workers — src/config/server.rs:64-68.

workers:
  mode: BackgroundQueue  # optional, default BackgroundQueue

WorkerMode (server.rs:71-83):

database

struct Database — src/config/database.rs:22-84. Only present/required when the with-db feature is enabled.

database:
  uri: postgres://root:12341234@localhost:5432/myapp_development  # required
  enable_logging: true       # required — SQLx statement logging
  min_connections: 1         # required
  max_connections: 1         # required
  connect_timeout: 500       # required, milliseconds
  idle_timeout: 500          # required, milliseconds
  acquire_timeout: 500       # optional, milliseconds
  auto_migrate: true         # optional, default false
  dangerously_truncate: false# optional, default false
  dangerously_recreate: false# optional, default false
  run_on_start: <sql/pragma> # optional

Note: the db_min_conn()=1 / db_max_conn()=20 / db_connect_timeout()=500 / db_idle_timeout()=500 helper functions in database.rs:86-100 are not defaults for Database itself (whose numeric fields have no #[serde(default)] and are required) — they are reused as the #[serde(default = ...)] values for the Postgres/Sqlite queue configs below.

logger

struct Logger — src/config/logger.rs:21-49.

logger:
  enable: true            # required
  pretty_backtrace: false # optional, default false
  level: debug            # required — off|trace|debug|info|warn|error
  format: compact         # required — compact|pretty|json
  override_filter: <str>  # optional — EnvFilter directive string
  file_appender:          # optional
    enable: true           # required within block
    non_blocking: false    # optional, default false, within block
    level: info            # required within block
    format: json           # required within block
    rotation: daily        # required within block — minutely|hourly|daily|never
    dir: ./logs            # optional, default "./logs"
    filename_prefix: <s>   # optional
    filename_suffix: <s>   # optional
    max_log_files: 7       # required within block

mailer

struct Mailer — src/config/mailer.rs:29-35.

# development: capture instead of sending
mailer:
  stub: false          # optional, default false
  smtp:
    enable: true       # required
    host: localhost    # required
    port: 1025         # required
    secure: false      # required — legacy shorthand, see below

# production: implicit TLS on port 465 (SMTPS)
mailer:
  smtp:
    enable: true
    host: smtp.example.com
    port: 465
    tls: implicit       # overrides `secure`; see below
    auth:
      user: [email protected]
      password: "<%= get_env(name='SMTP_PASSWORD') %>"
    hello_name: <string> # optional — EHLO client id

Effective TLS mode is resolved by SmtpMailer::tls_mode() (mailer.rs:76-87): if tls is set, it wins outright; otherwise secure: true → Starttls, secure: false → None.

queue

enum QueueConfig — src/config/queue.rs:5-14, #[serde(tag = "kind")] with variants Redis, Postgres, Sqlite.

# kind: Redis
queue:
  kind: Redis
  uri: redis://127.0.0.1                # required
  dangerously_flush: false              # optional, default false
  queues: [high, low]                   # optional — priority order, first = most important
  num_workers: 2                        # optional, default 2
  # reaper:                             # optional, disabled by default (opt-in)
  #   age_minutes: 10                   # requeue jobs stuck in `processing` for longer than this
  #   interval_seconds: 60              # optional, default 60 — how often to sweep

# kind: Postgres
queue:
  kind: Postgres
  uri: postgres://...                   # required
  dangerously_flush: false              # optional, default false
  enable_logging: false                 # optional, default false
  max_connections: 20                   # optional, default 20
  min_connections: 1                    # optional, default 1
  connect_timeout: 500                  # optional, default 500 (ms)
  idle_timeout: 500                     # optional, default 500 (ms)
  poll_interval_sec: 1                  # optional, default 1
  num_workers: 2                        # optional, default 2
  # reaper:                             # optional, disabled by default (opt-in)
  #   age_minutes: 10                   # requeue jobs stuck in `processing` for longer than this
  #   interval_seconds: 60              # optional, default 60 — how often to sweep

# kind: Sqlite (same shape as Postgres)
queue:
  kind: Sqlite
  uri: sqlite://...
  poll_interval_sec: 1                  # optional, default 1 (own default fn)
  # ...remaining keys identical to Postgres, including the optional `reaper`

cache

enum CacheConfig — src/config/cache.rs:4-16, #[serde(tag = "kind")]. Default variant: Null (#[default], cache.rs:14-15) — this is what Config.cache's #[serde(default)] produces when the cache key is omitted entirely.

cache:
  kind: InMem              # requires the `cache_inmem` feature
  max_capacity: 33554432   # optional, default 33554432 bytes (32 MiB)

# --- or ---
cache:
  kind: Redis              # requires the `cache_redis` feature
  uri: redis://...         # required
  max_size: 100            # required — max pool connections

# --- or (default) ---
cache:
  kind: Null               # no-op cache; used when `cache` key is omitted

If the corresponding feature (cache_inmem / cache_redis) is not compiled in, that kind value will fail to deserialize.

initializers, settings, scheduler

• initializers: Option<BTreeMap<String, serde_json::Value>> (mod.rs:75,106) — a free-form map consumed by app initializers (e.g. an oauth2 initializer reading initializers.oauth2). Keys and shapes are defined by whichever initializer reads them, not by Config itself.
• settings: Option<serde_json::Value> (mod.rs:88-89) — arbitrary app-defined settings, deserialize your own type from ctx.config.settings.
• scheduler: Option<scheduler::Config> (mod.rs:91) — struct and keys owned by the scheduler area; not detailed on this page.

Environment variables

Secrets (JWT secret, SMTP password, database uri credentials) are plain String fields with no dedicated vault type; the convention is to inject them via <%= get_env(name="...") %> at config-load time rather than hardcoding them in the YAML file.