Configuration Sources#

Tinyauth supports three configuration sources — YAML files, environment variables, and CLI flags — through a pluggable loader chain powered by the paerser library. All sources populate the same Config struct, and later loaders in the chain override earlier ones.

Loader Chain and Priority#

At startup, three loaders are registered in order 1:

FileLoader → FlagLoader → EnvLoader

Each loader implements the ResourceLoader interface from paerser/cli. The chain executes sequentially; the first loader that returns done = true short-circuits further loading. Because EnvLoader runs last, environment variables have the highest priority, overriding both flags and file values.

FileLoader#

FileLoader resolves the config file path from either:

1. The --traefik.configfile CLI flag (parsed at load time), or
2. The TINYAUTH_CONFIGFILE environment variable as a fallback.

If neither is set it is a no-op. When a path is found, it calls file.Decode() from paerser/file to unmarshal the file (YAML, TOML, or JSON are all supported by the underlying decoder) into the Config struct 2.

Note: The flag key is named traefik.configfile internally — a legacy of paerser's Traefik origins — but the env var is the idiomatic TINYAUTH_CONFIGFILE 3.

EnvLoader#

EnvLoader scans all environment variables for the prefix TINYAUTH_ 4 and calls env.Decode() from paerser/env. Field names follow the TINYAUTH_<SECTION>_<KEY> convention, e.g. TINYAUTH_SERVER_PORT or TINYAUTH_DATABASE_DRIVER 5. Nested structs use additional underscore-separated segments, and map keys are bracketed: TINYAUTH_AUTH_USERATTRIBUTES_[NAME]_EMAIL 6.

FlagLoader#

FlagLoader parses CLI arguments via flag.Decode() from paerser/flag. Flags use dot-separated names mirroring the struct hierarchy (e.g. --server.port=3000). If no args are present, it short-circuits immediately 7.

Paerser Processing Pipeline#

All three loaders share the same internal pipeline from paerser:

1. Source → flat map – flags, env vars, or file contents are normalized to key=value pairs.
2. Flat map → node tree – keys are split into a hierarchical Node structure.
3. Node tree + struct reflection → typed struct – paerser/parser walks the target struct and fills fields with typed values.

Config Struct and Defaults#

The Config struct covers all configuration domains: Server, Database, Auth, OAuth, OIDC, Apps, LDAP, Tailscale, UI, Log, Analytics, Resources, and Experimental. Defaults are set by NewDefaultConfiguration(env) before any loaders run; loaders overlay values on top. When running in Docker, path defaults (e.g. for the database) are adjusted automatically.

tinyauth config Command#

The registered configCmd 8 exposes the resolved configuration at runtime, which is useful for debugging which values were ultimately loaded from which source.

Full Configuration Reference#

The auto-generated configuration reference in the docs repository lists every supported env var, flag, and its default value. It is generated from the Config struct and is the canonical source for available options.

Key Files#