Configuration

Andurel keeps configuration in the generated application. The config package loads local .env, parses process environment values into typed structs, validates them, and supplies them through Fx. Framework packages receive typed values and never read environment variables themselves.

Loading, parsing, and precedence

config.LoadEnvironment() runs before Fx construction. A constructor default applies only when a key is absent, so an explicitly empty string differs from an unset value. Parsers support required and optional strings, integers, booleans, floats, Go durations, and comma-separated lists.

Durations use values such as 250ms, 10s, 5m, or 1h30m. Lists are split on commas, trimmed, and empty items removed. Each constructor joins conversion and semantic errors and returns context such as config: database: ....

Typed providers and process scope

Providers are independent: NewApp, NewAuth, NewHTTP, NewSession, NewDatabase, NewQueueInsert, NewQueueWorker, NewTelemetry, NewMail, NewMailTransport, and optional NewInertia.

Fx calls only providers used by a process. Web needs HTTP and queue insertion; queue needs worker policy but not HTTP. Keep types distinct so a process cannot accidentally acquire a capability it should not own.

Application and HTTP

Behind a proxy, a normal split is DOMAIN=app.example.com, PROTOCOL=https, HOST=0.0.0.0, and an internal port. Credentialed wildcards are rejected.

Database

Budget connections across all web and queue replicas, leaving room for migrations and administration. See Storage.

Sessions and authentication

Production values belong in deployment secrets, never committed .env. Pepper rotation moves the old current value into PREVIOUS_PEPPERS for a bounded migration window. Session and signing-key rotation may invalidate live cookies or tokens. The cookie name includes project and environment to avoid cross-environment collisions.

Queue configuration

Insertion reads only QUEUE_MAX_ATTEMPTS and QUEUE_SCHEMA. Workers clone that base and add processing policy:

Edit NewQueueWorker for named queues or per-queue concurrency. Validation covers names, schemas, ranges, durations, and relationships.

Email and telemetry

DEFAULT_SENDER_SIGNATURE defaults to noreply@DOMAIN. EMAIL_PROVIDER selects an installed transport. Development defaults to mailpit, with MAILPIT_HOST=0.0.0.0 and MAILPIT_PORT=1025. Production requires an installed provider such as the aws-ses extension and its own credential configuration.

Inertia and SSR

INERTIA_SSR_LISTEN is the address Node binds. INERTIA_SSR_URL is the HTTP client URL and may be a service hostname. Pages still opt into SSR individually. See Inertia and SSR.

Adding application settings

Add a focused type and constructor, validate it, register the constructor in config.Module, and inject the type only where needed:

 1type Search struct { Endpoint string; Timeout time.Duration }
 2
 3func NewSearch() (Search, error) {
 4    env := newEnvironment()
 5    cfg := Search{
 6        Endpoint: env.RequiredString("SEARCH_ENDPOINT"),
 7        Timeout: env.Duration("SEARCH_TIMEOUT", 2*time.Second),
 8    }
 9    if err := env.Err(); err != nil { return Search{}, err }
10    if cfg.Timeout <= 0 { return Search{}, errors.New("SEARCH_TIMEOUT must be positive") }
11    return cfg, nil
12}

Provide a Clone method for mutable maps or slices. Startup errors should remain fatal; continuing with partial defaults converts a clear deployment failure into request-time corruption or insecure behavior.