Skip to content

Configuration

The backend uses a two-layer configuration system:

  1. YAML files hold non-sensitive defaults (ports, hosts, timeouts, feature flags).
  2. Environment variables override secrets and infrastructure-injected values (DB password, JWT secret, OAuth client secrets, API keys).

The loader lives in backend/config/config.go. Everything goes through config.Load() which is invoked once at startup from cmd/server/main.go.

YAML layering

config.Load() reads ENV from the environment (defaults to local) and loads:

config.{ENV}.yaml   (preferred)
config.yaml         (fallback if env-specific file is missing)

The string production is normalised to prod so both work as ENV values.

Files in this repo:

File Purpose
backend/config.yaml Base / shared defaults
backend/config.local.yaml Local Docker stack (localhost, RustFS endpoint)
backend/config.dev.yaml Dev cloud environment
backend/config.prod.yaml Production

What goes in YAML vs env

YAML: ports, hostnames, JWT expiry, worker concurrency, object storage bucket/region, WebAuthn RP config, email from address, Photon URL, exchange-rate API URL. Env vars: all secrets: DB password, JWT secret, OAuth client secrets, Stripe keys, object-storage (R2) keys, asset signing key.

Env file precedence

After parsing YAML, config.Load() loads .env.{ENV} via joho/godotenv. If that file is missing, it falls back to a bare .env. Variables already present in the OS environment are not overridden.

Then every secret-bearing field is read from os.Getenv(...) and overwrites the YAML value when set. This means env vars always win over YAML.

# Override the DB host from config.local.yaml without editing the file
DB_HOST=postgres.internal go run ./cmd/server

The Config struct

The full top-level shape (backend/config/config.go):

type Config struct {
    Server       ServerConfig        // port, env (typed), allowed_origins, trusted proxies
    Database     DatabaseConfig      // host, port, user, password, dbname, sslmode, log_level
    Redis        RedisConfig         // host, port, password
    JWT          JWTConfig           // secret, expiry (time.Duration)
    Email        EmailConfig         // api_key, ads_enabled (env only), base_url, from, logo_base_url
    Worker       WorkerConfig        // concurrency
    Stripe       StripeConfig        // secret_key, webhook_secret, price_ids, urls
    Google       GoogleConfig        // client_id, client_secret, places_api_key
    GooglePlaces GooglePlacesConfig  // api_key, ads_enabled (alias)
    Line         LineConfig          // client_id, client_secret
    Apple        AppleConfig         // client_id, service_id, team_id, key_id, auth_key_p8 (env only)
    WebAuthn     WebAuthnConfig      // rp_id, rp_display_name, rp_origin
    ObjectStorage ObjectStorageConfig // bucket, region, access_key_id, secret_access_key,
                                     // public_url (assets host), endpoint, use_path_style
    Logger       LoggerConfig        // level, format
    Klipy        KlipyConfig         // api_key, ads_enabled
    Photon       PhotonConfig        // url, timeout, enabled
    Semantic     SemanticConfig      // enabled, base_url, model, api_key, timeout, json_mode
    Location     LocationConfig      // background_paid_enrichment (off locally to keep seeding Serper-free)
    Resolution   ResolutionConfig    // Serper keys and switches, plus capture-picker harvesting: enable_burst_seed,
                                     // burst_tile_ttl_days, burst_daily_cap, burst_uncapped, burst_user_daily_fills,
                                     // burst_user_daily_auto, burst_share_fill/_explicit/_auto/_pages,
                                     // burst_slot_limit, burst_photo_daily_ceiling, burst_fill_budget_ms, burst_zoom_150/_300/_500, burst_zoom_area,
                                     // burst_search_more_cell_per_hour
    RankWeights  RankWeightsConfig   // search-ranking weight vector; env-swappable, defaults to the shipped values
    Abuse        AbuseConfig         // blocker thresholds, never-block allowlist, Worker HMAC secret (security/ip-blocker.md)
    Legal        LegalConfig         // policy_notices_enabled (true only in prod), policy_notice_rate (emails/s, default 4)
    FX           FXConfig            // base_url (public Frankfurter API; empty disables), timeout, allow_private
    Support      SupportConfig       // address (support mailbox, default support@tomoda.life), inbound_secret (env only)
    Assist       AssistConfig        // review model for Backstage assist tasks: base_url, model, timeout (default 30s), allow_private, daily_token_budget; api_key env only. Empty base_url or model leaves those tasks without a model
    Crashes      CrashesConfig       // base_url (default https://sentry.io), org and project (set in each `config.*.yaml`), api_token (`CRASHES_API_TOKEN`, env only); empty token turns the Backstage view off
}

Database.DSN() / Redis.Address() are helpers that downstream code uses to assemble connection strings.

The environment is a typed value

Server.Env is a config.Environment, not a string. config.ParseEnvironment resolves it once at load time from the config file's server.env (falling back to the ENV var) and rejects any value it does not know, so a typo fails the boot instead of silently landing in a non-production branch.

Constant Value Notes
config.EnvLocal local Developer machine. An empty value parses to this.
config.EnvTest test Test harnesses.
config.EnvDev dev Dev cluster. development parses to this.
config.EnvProd prod Production. production parses to this.

Compare with the helpers, never a string literal: env.IsProduction() gates HSTS (internal/middleware/security.go), the Swagger blackout (internal/wiring/router.go), and login throttling (internal/middleware/rate_limiter.go). env.IsLocal() covers local plus test, and is what relaxes the credential checks below.

Required vs optional

Config.Validate() runs at the end of Load() and hard-fails the boot on settings that would silently degrade security:

Check Rule
JWT_SECRET At least 32 bytes. golang-jwt happily signs with a zero-length HMAC key, so nothing downstream catches an empty one.
Placeholder credentials The local development placeholders are rejected outside local and test.
server.allowed_origins Non-empty, and no * outside local and test.

In local and test only, applyLocalDevDefaults substitutes obviously-insecure placeholder credentials and a wildcard CORS origin, so a fresh checkout boots with no secrets file. It logs a warning each time, and Validate rejects those same placeholders in dev and prod.

Everything else is still validated at the point of use (e.g. EmailService.SendEmail errors when APIKey or BaseURL is missing), so boot succeeds without them and the affected feature fails at runtime.

CORS and proxy topology

Server.AllowedOrigins feeds the CORS middleware in internal/wiring/router.go. Native clients send no Origin header and are unaffected; this list only constrains browsers. config.dev.yaml and config.prod.yaml name their real origins, and CORS_ALLOWED_ORIGINS (comma-separated) overrides the file so a cluster can add one without a rebuild.

Server.TrustedProxyCount and Server.TrustedProxies describe how many reverse-proxy hops sit in front of the pod and which CIDRs may set X-Forwarded-For. When TrustedProxies is non-empty it takes precedence and the hop count is ignored. Dev and prod trust the k3s pod CIDR plus Cloudflare's edge ranges; see Client IP resolution. Both override via TRUSTED_PROXY_COUNT / TRUSTED_PROXIES.

Secrets and GCP Secret Manager

Production runs on the k3s cluster and pulls secrets from GCP Secret Manager via the External Secrets Operator. No .env files exist in production containers.

For local development, the script scripts/dev/pull-secrets.sh fetches the same secrets out of GCP and exports them into your shell:

# Pull and export into the current shell
eval $(./scripts/dev/pull-secrets.sh --export)

# Or pull and exec the backend in one step
./scripts/dev/pull-secrets.sh --run

task dev wraps this: if gcloud auth print-access-token succeeds, it runs pull-secrets.sh --export automatically. Otherwise it falls back to a hard-coded set of local-only defaults (DB_USER=tomoda, DB_PASSWORD=tomoda123, RustFS creds, empty Redis password).

To enable secret pulling locally:

gcloud auth login
gcloud config set project development-485000

Never commit .env.* files

.env.local, .env.dev, .env.prod are all gitignored. Treat them as ephemeral — regenerate from GCP whenever you need them.

Common env vars

Category Variables
Database DB_HOST, DB_PORT, DB_USER, DB_PASSWORD, DB_NAME, DB_SSLMODE
Auth JWT_SECRET
OAuth GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GOOGLE_PLACES_API_KEY, APPLE_CLIENT_ID, APPLE_SERVICE_ID, APPLE_TEAM_ID, APPLE_KEY_ID, APPLE_AUTH_KEY_P8
Billing STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET
Email & APIs EMAIL_APIKEY, SUPPORT_INBOUND_SECRET, CRASHES_API_TOKEN, ASSIST_API_KEY, KLIPY_API_KEY, KLIPY_ADS_ENABLED, PHOTON_URL
Storage STORAGE_ACCESS_KEY_ID, STORAGE_SECRET_ACCESS_KEY, STORAGE_ENDPOINT, STORAGE_PUBLIC_URL, ASSET_SIGNING_KEY
Redis REDIS_HOST, REDIS_PORT, REDIS_PASSWORD
App ENV, FRONTEND_URL, GIN_MODE, SERVER_MODE, CORS_ALLOWED_ORIGINS, TRUSTED_PROXY_COUNT, TRUSTED_PROXIES
Abuse ABUSE_VIOLATION_THRESHOLD, ABUSE_VIOLATION_WINDOW, ABUSE_BLOCK_DURATIONS, ABUSE_ALLOWLIST, WORKER_AUTH_SECRET
Ranking RANK_WEIGHT_NAME, RANK_WEIGHT_PROXIMITY, RANK_WEIGHT_POPULARITY, RANK_WEIGHT_PROMINENCE, RANK_WEIGHT_SOURCE, RANK_WEIGHT_SEMANTIC, RANK_WEIGHTS_REFRESH_INTERVAL

RANK_WEIGHT_* supply the composite search-ranking weight vector as a fallback. Each defaults to its shipped value, so an unset environment ranks byte-identically to the compile-time constants. Effective weights resolve active ranking_weights DB row > env config > shipped default: an approved retune is applied to the DB and hot-swapped in without a redeploy (see Locations → Ranking). RANK_WEIGHTS_REFRESH_INTERVAL (default 2m, 0 disables) sets how often the API ranker re-reads the active row.

For the canonical, exhaustive list, see Reference → Environment Variables. For how secrets are provisioned and rotated, see Infrastructure → Secrets.

Where ObjectStorage.PublicURL matters

ObjectStorage.PublicURL is the public host for uploaded files (e.g. https://assets.tomoda.life). It is pinned per environment in config.<env>.yaml (object_storage.public_url); local dev gets the RustFS host from config.local.yaml. STORAGE_PUBLIC_URL overrides it, for example when scripts/dev/pull-secrets.sh --full points local dev at the R2 dev bucket.

Debug

When the loader runs, it prints a redacted snippet of the Stripe webhook secret to stdout so you can verify env merging succeeded:

Loaded config from .env.local
Stripe Webhook Secret loaded: whsec_xxxx...

If you see Stripe Webhook Secret NOT loaded or too short, your env file isn't being picked up.