From 01e875a45ec58e247ac022fbaa5d88681398e0f7 Mon Sep 17 00:00:00 2001 From: Wynne Pirini Date: Sun, 8 Nov 2026 07:56:11 +1300 Subject: [PATCH] fix(config): document and warn when stored settings shadow env vars (#238) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Email and Google OAuth settings live in the database once configured, and those stored values take precedence over the environment. On first boot the env vars *seed* the database (seedSMTPToDB only writes when smtp_host is empty), so changing EMAIL_SMTP_* afterwards has no effect. That is intended — the UI is the live source of truth — but it happened silently, which is what #238 reports. No behaviour change. Two things make it visible: - DEPLOY.md gains a precedence note above the env table, and the EMAIL_SMTP_* and GOOGLE_CLIENT_ID rows now say they seed the database rather than "can also be set later". - Boot logs a WARN naming the ignored variables when a set env var differs from the stored value. Names only, never values. Only variables whose env default is empty are compared (host, user; Google client id). EMAIL_SMTP_PORT and EMAIL_FROM_ADDRESS default to non-empty strings, so including them would warn about values the operator never set. Verified on a real boot sequence: first start with EMAIL_SMTP_HOST=a.example.com seeds the DB; restarting with b.example.com logs `mailer: ignoring environment settings ... ignored=[EMAIL_SMTP_HOST]` and leaves the stored host at a.example.com; restarting with the matching value logs nothing. Flipping precedence instead (env over DB) was considered and rejected: it would make Settings → Email editable but not authoritative, and a stale env var would silently override a UI change after any restart. --- DEPLOY.md | 12 +++++-- internal/server/server.go | 41 ++++++++++++++++++++++++ internal/server/shadowed_env_test.go | 48 ++++++++++++++++++++++++++++ 3 files changed, 99 insertions(+), 2 deletions(-) create mode 100644 internal/server/shadowed_env_test.go diff --git a/DEPLOY.md b/DEPLOY.md index 6ea0f5b6..35cfa98d 100644 --- a/DEPLOY.md +++ b/DEPLOY.md @@ -53,6 +53,14 @@ backup method. The email, calendar and other integration settings below still ap ## 1. Configuration (environment variables) +> **Settings saved in the UI win over environment variables.** Email (SMTP/Resend) and +> Google OAuth credentials are stored in the database. Environment variables are read only +> when nothing is stored: on first boot they *seed* the database, and from then on the +> stored values take precedence. Changing an env var after that has no effect until you +> clear the matching setting in Settings → Email / Settings → Google. Calnode logs a +> warning at startup naming every variable it is ignoring, so this is visible rather than +> silent. + | Variable | Required | Default | Notes | |---|---|---|---| | `CALNODE_ENCRYPTION_KEY` | **prod: yes** | — | KEK input (Argon2id). **Required when `BASE_URL` is https** — the app refuses to start without it. Use a long random string: `openssl rand -hex 32`. **Losing it makes encrypted data unrecoverable** unless you set the recovery secret below. | @@ -61,11 +69,11 @@ backup method. The email, calendar and other integration settings below still ap | `PUBLIC_BASE_URL` | no | = `BASE_URL` | Booker-facing host for booking links/emails, if different from the identity host. | | `DATABASE_URL` | no | `sqlite://./data/calnode.db` | Point at the persistent volume, e.g. `sqlite:///data/calnode.db`. | | `PORT` | no | `3000` | The app listens on `$PORT`. Many platforms inject their own (Railway injects `8080`) — let them. | -| `EMAIL_SMTP_HOST` / `_PORT` / `_USER` / `_PASS` | no¹ | — / `587` | SMTP. Can also be set later in Settings → Email (DB-stored, encrypted). | +| `EMAIL_SMTP_HOST` / `_PORT` / `_USER` / `_PASS` | no¹ | — / `587` | SMTP. Seeds Settings → Email on first boot; once stored there, the database value wins (see the precedence note above). | | `EMAIL_SMTP_CONNECT_HOST` / `EMAIL_SMTP_CONNECT_PORT` | no | SMTP host / port | TCP relay address, loaded at startup. Applies to environment and database SMTP settings; TLS and authentication still use the SMTP host. | | `EMAIL_SMTP_TLS` / `_STARTTLS` | no | `false` | `STARTTLS` for 587, implicit `TLS` for 465. | | `EMAIL_FROM_ADDRESS` / `EMAIL_FROM_NAME` | no | `bookings@localhost` / `Calnode` | The From identity. | -| `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` | no | — | Google sign-in + calendar. Can also be set in Settings → Google OAuth. | +| `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` | no | — | Google sign-in + calendar. Seeds Settings → Google OAuth on first boot; once stored there, the database value wins (see the precedence note above). | | `LITESTREAM_REPLICA_URL` | recommended | — | Enables continuous SQLite backup (see §6). | | `COOKIE_SECURE` | no | https→true | Override cookie Secure flag; defaults from `BASE_URL` scheme. | | `TRUSTED_PROXY_CIDRS` | no | — | Comma-separated CIDRs (a bare address = one host) whose `X-Forwarded-For` is believed when keying per-IP rate limits, e.g. `10.0.0.0/8`. Include a fronting CDN's own ranges so the walk steps over its edge and lands on the visitor. Unset ⇒ the header is ignored and the limit keys on the TCP peer, so behind a CDN every visitor shares one bucket. **Only list networks you control**: anything in the list can name any client IP it likes. Single-value vendor headers (`CF-Connecting-IP`, `X-Real-IP`) are never read, from any peer. | diff --git a/internal/server/server.go b/internal/server/server.go index 5d904b4d..8116b500 100644 --- a/internal/server/server.go +++ b/internal/server/server.go @@ -58,6 +58,30 @@ func newMCPStreamableHandler(srv *mcp.Server) http.Handler { ) } +// envEntry pairs one environment-sourced setting with the value the database +// resolved for the same thing. Only the name is ever surfaced — never a value. +type envEntry struct { + name string + env string + db string +} + +// shadowedEnv returns the names of environment variables that are set but overridden +// by stored settings, so boot can say so instead of ignoring them silently (#238). +// A variable that agrees with the database, or is unset, is not reported: only a real +// divergence is a surprise worth warning about. Fields whose environment default is +// non-empty (EMAIL_SMTP_PORT, EMAIL_FROM_ADDRESS) are deliberately not compared here — +// they would warn for values the operator never set. +func shadowedEnv(entries []envEntry) []string { + var out []string + for _, e := range entries { + if e.env != "" && e.env != e.db { + out = append(out, e.name) + } + } + return out +} + func BuildHandler(ctx context.Context, cfg *config.Config, db *sql.DB, logger *slog.Logger) (*handler.Handler, func()) { h := handler.New(db, logger) h.SetBaseURL(cfg.BaseURL) @@ -123,6 +147,16 @@ func BuildHandler(ctx context.Context, cfg *config.Config, db *sql.DB, logger *s live.Swap(m) logger.Info("mailer: configured from database", "transport", string(transport), "host", dbSMTP.Host, "port", dbSMTP.Port) + // Environment SMTP settings are ignored once the database holds a configuration + // (they seeded it on first boot). Say which ones, so a redeploy that changes an + // env var does not fail silently (#238). + if ignored := shadowedEnv([]envEntry{ + {"EMAIL_SMTP_HOST", cfg.SMTPHost, dbSMTP.Host}, + {"EMAIL_SMTP_USER", cfg.SMTPUser, dbSMTP.User}, + }); len(ignored) > 0 { + logger.Warn("mailer: ignoring environment settings — the database configuration takes precedence; change it in Settings → Email, or clear the stored settings there to fall back to the environment", + "ignored", ignored) + } case cfg.SMTPHost != "": m, _ := h.BuildMailer(handler.SMTPConfig{ @@ -171,6 +205,13 @@ func BuildHandler(ctx context.Context, cfg *config.Config, db *sql.DB, logger *s googleClientID = dbGoogle.ClientID googleClientSecret = dbGoogle.ClientSecret logger.Info("Google OAuth: credentials loaded from database") + // Same silent-override trap as SMTP above (#238). + if ignored := shadowedEnv([]envEntry{ + {"GOOGLE_CLIENT_ID", cfg.GoogleClientID, dbGoogle.ClientID}, + }); len(ignored) > 0 { + logger.Warn("Google OAuth: ignoring environment settings — the database configuration takes precedence; change it in Settings → Google, or clear the stored settings there to fall back to the environment", + "ignored", ignored) + } } // Build one calendar Service and register every configured provider into it. diff --git a/internal/server/shadowed_env_test.go b/internal/server/shadowed_env_test.go new file mode 100644 index 00000000..36f3c321 --- /dev/null +++ b/internal/server/shadowed_env_test.go @@ -0,0 +1,48 @@ +package server + +import ( + "reflect" + "testing" +) + +// #238: env vars that are set but shadowed by the database were ignored silently. +func TestShadowedEnv(t *testing.T) { + cases := []struct { + name string + entries []envEntry + want []string + }{ + { + name: "nothing set", + entries: []envEntry{{"EMAIL_SMTP_HOST", "", "smtp.example.com"}}, + }, + { + name: "set and agreed", + entries: []envEntry{{"EMAIL_SMTP_HOST", "smtp.example.com", "smtp.example.com"}}, + }, + { + name: "set and differs", + entries: []envEntry{{"EMAIL_SMTP_HOST", "new.example.com", "old.example.com"}}, + want: []string{"EMAIL_SMTP_HOST"}, + }, + { + name: "mixed", + entries: []envEntry{ + {"EMAIL_SMTP_HOST", "new.example.com", "old.example.com"}, + {"EMAIL_SMTP_USER", "", "user"}, + {"GOOGLE_CLIENT_ID", "same", "same"}, + {"EMAIL_SMTP_PASS", "secret", ""}, + }, + want: []string{"EMAIL_SMTP_HOST", "EMAIL_SMTP_PASS"}, + }, + } + + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + got := shadowedEnv(tc.entries) + if !reflect.DeepEqual(got, tc.want) { + t.Errorf("shadowedEnv = %v; want %v", got, tc.want) + } + }) + } +}