Configuration

Configuration is application code in the config package. It reads the process environment into typed structs, validates each one at startup, and fails fast with an error that names the section.

How configuration loads

Each process entry loads .env and then builds the configuration it needs:

1// cmd/app/main.go
2if err := env.Load(); err != nil {
3    return err
4}
5
6cfg, err := config.New()
7if err != nil {
8    return err
9}

• env.Load() reads KEY=VALUE pairs from .env and sets them in the process environment. Keys already present in the process environment win, so a deployment secret overrides the file. A missing .env is not an error; required keys then have to come from the real environment.
• config.New() calls one constructor per section (NewApp, NewHTTP, NewAuth, NewSession, NewCache, NewDatabase, NewQueueInsert, NewQueueWorker, NewTelemetry, NewMail, NewInertia) and returns one config.Config value.
• Every constructor reads with pkg/env, validates, and wraps its failures as config: <section>: .... Malformed values are startup errors, not request-time surprises.
• cmd/migrate and cmd/seeds call only config.NewDatabase(). They do not need HTTP, session, mail or Inertia settings.
• Nothing outside config/ reads environment variables. internal/runtime receives typed values and passes them down.

Application and HTTP

Configured host origins (PROTOCOL + HOST_PRIMARY and any named hosts) are trusted for CORS and CSRF automatically. Behind a proxy, a normal split is HOST_PRIMARY=app.example.com, PROTOCOL=https, HOST=0.0.0.0, and an internal PORT.

Database

Budget connections across every web and queue replica, leaving room for migrations and administration. See Database.

Sessions and authentication

Production values belong in deployment secrets, never in a committed .env. The cookie name is derived as app_sess_<project-slug>-<environment>, so environments on the same hostname do not share sessions. Rotating the session keys invalidates live cookies; rotating PEPPER moves the old value into PREVIOUS_PEPPERS until users have signed in again. See Authentication.

Cache

Rate-limit counters live in this store, so a multi-replica deployment needs the Redis driver for shared limits.

Queue

Both queue configs start from storage.DefaultQueueConfig(). Insertion reads QUEUE_MAX_ATTEMPTS and QUEUE_SCHEMA; the worker clones that base and adds processing policy:

Named queues and per-queue concurrency are code, not environment: edit NewQueueWorker in config/queue.go. See Queues.

Email and telemetry

DEFAULT_SENDER_SIGNATURE defaults to noreply@ plus the primary host, with any listen port removed. EMAIL_PROVIDER selects the transport:

• mailpit (the default) sends to Mailpit on MAILPIT_HOST / MAILPIT_PORT (0.0.0.0 / 1025) and is refused in production.
• smtp uses SMTP_HOST, SMTP_PORT (default 587), SMTP_USERNAME, SMTP_PASSWORD, and SMTP_TLS (starttls, tls, or none).

Inertia and SSR

SSR is opted into per page, not switched on globally. The shipped .env.example sets INERTIA_SSR_FAIL_FAST=false for local development, where no SSR process runs; a production deployment should decide the value explicitly. See Views.

Adding an application setting

Add a focused type, a constructor that reads and validates it, a field on config.Config, and a call from config.New:

 1type Search struct {
 2    Endpoint string
 3    Timeout  time.Duration
 4}
 5
 6func NewSearch() (Search, error) {
 7    e := env.New()
 8    cfg := Search{
 9        Endpoint: e.String("SEARCH_ENDPOINT", ""),
10        Timeout:  e.Duration("SEARCH_TIMEOUT", 2*time.Second),
11    }
12    if err := e.Err(); err != nil {
13        return Search{}, fmt.Errorf("config: search: %w", err)
14    }
15    if cfg.Endpoint == "" {
16        return Search{}, fmt.Errorf("config: search: SEARCH_ENDPOINT is required")
17    }
18    if cfg.Timeout <= 0 {
19        return Search{}, fmt.Errorf("config: search: SEARCH_TIMEOUT must be positive")
20    }
21
22    return cfg, nil
23}

For a set of related fields, collect failures with validation.NewBuilder() and return b.Err() instead of testing each one by hand. Then construct the value in config.New, store it on config.Config, and pass it to the one dependency that needs it in internal/runtime. Copy maps or slices before another process mutates them; storage.QueueConfig.Clone is the pattern to follow.

Keep startup errors fatal. Continuing with a partial default turns a clear deployment failure into request-time corruption.