Every setting can be given as an environment variable (closes #128)

Each config key can now be set by PIXA_ plus the key in upper case
("." written as "_"), and the port by PORT. A present variable, even
an empty one, is read before the config file through the existing
typed getters, so every existing check covers it; errors name the key
and the variable, never the signing key or metrics password. A
variable named in the file's env: section overrides both. An empty
string for blocked_networks or trusted_proxies is now an empty list.
The image no longer bakes in config.docker.yml or passes --config; its
HEALTHCHECK probes ${PORT:-8080}. The config file is looked for under
/etc/pixa rather than /etc/pixad. Also covers #99.

Model: opus-5-5

internal/config/config.go

@@ -16,7 +16,6 @@ import (
 
 	"git.eeqj.de/sneak/smartconfig"
 	"go.uber.org/fx"
-	"sneak.berlin/go/pixa/internal/globals"
 	"sneak.berlin/go/pixa/internal/logger"
 )
 
@@ -92,8 +91,7 @@ var (
 type Params struct {
 	fx.In
 
-	Globals *globals.Globals
-	Logger  *logger.Logger
+	Logger *logger.Logger
 }
 
 // Config holds application configuration values.
@@ -137,24 +135,27 @@ type Config struct {
 	CacheMaxBytes int64
 
 	// cacheMaxBytesExplicit records whether cache_max_bytes was
-	// explicitly set in the configuration file. Explicit values are
-	// used exactly as given; only an omitted key gets the computed
-	// default (and its floor) in resolveCacheMaxBytes.
+	// explicitly set, in the environment or the configuration file.
+	// Explicit values are used exactly as given; only an omitted key
+	// gets the computed default (and its floor) in resolveCacheMaxBytes.
 	cacheMaxBytesExplicit bool
 }
 
-// New creates a new Config instance by loading configuration from file.
+// New creates a new Config instance from the environment and the
+// config file.
 func New(_ fx.Lifecycle, params Params) (*Config, error) {
 	log := params.Logger.Get()
-	name := params.Globals.Appname
 
-	sc, err := loadConfigFile(log, name)
+	// Look for the config file under the project name (/etc/pixa/,
+	// ~/.config/pixa/), matching the /var/lib/pixa state directory,
+	// not under the daemon name pixad.
+	sc, err := loadConfigFile(log, "pixa")
 	if err != nil {
 		return nil, err
 	}
 
 	if sc == nil {
-		log.Info("no config file found, using defaults")
+		log.Info("no config file found, using environment variables and defaults")
 	}
 
 	c, err := newFromSmartConfig(sc)
@@ -179,22 +180,23 @@ func New(_ fx.Lifecycle, params Params) (*Config, error) {
 	return c, nil
 }
 
-// newFromSmartConfig constructs a Config from a loaded smartconfig
-// instance and validates it. A nil sc means no config file was found,
-// in which case every option takes its default value. A key that is
-// present but unparseable or invalid is an error: defaults apply only
-// to omitted keys, never to invalid explicit values.
+// newFromSmartConfig constructs a Config from the environment and a
+// loaded smartconfig instance, and validates it. A nil sc means no
+// config file was found, in which case every option the environment
+// does not set takes its default value. A key that is present but
+// unparseable or invalid is an error: defaults apply only to omitted
+// keys, never to invalid explicit values.
 func newFromSmartConfig(sc *smartconfig.Config) (*Config, error) {
 	if sc != nil {
 		err := validateKnownKeys(sc)
 		if err != nil {
 			return nil, err
 		}
+	}
 
-		err = validateAllowlistHostsValue(sc)
-		if err != nil {
-			return nil, err
-		}
+	err := validateAllowlistHostsValue(sc)
+	if err != nil {
+		return nil, err
 	}
 
 	blockedNetworks, err := parseCIDRList(sc, keyBlockedNetworks)
@@ -238,10 +240,8 @@ func newFromSmartConfig(sc *smartconfig.Config) (*Config, error) {
 	// The computed default for cache_max_bytes needs a validated
 	// state_dir, so it is resolved later (resolveCacheMaxBytes); here
 	// we only record whether the operator set the key explicitly.
-	if sc != nil {
-		if _, present := sc.Get(keyCacheMaxBytes); present {
-			c.cacheMaxBytesExplicit = true
-		}
+	if _, present := lookupValue(sc, keyCacheMaxBytes); present {
+		c.cacheMaxBytesExplicit = true
 	}
 
 	// Build DBURL from StateDir if not explicitly set. The derived URL
@@ -249,12 +249,9 @@ func newFromSmartConfig(sc *smartconfig.Config) (*Config, error) {
 	// explicitly empty value.
 	c.DBURL = loader.stringVal(keyDBURL, "")
 	if c.DBURL == "" && loader.err == nil {
-		if sc != nil {
-			if _, present := sc.Get(keyDBURL); present {
-				return nil, fmt.Errorf(
-					"config key %q: %w; omit the key to derive it from state_dir",
-					keyDBURL, errValueEmpty)
-			}
+		if _, present := lookupValue(sc, keyDBURL); present {
+			return nil, fmt.Errorf("%s: %w; omit it to derive it from state_dir",
+				settingName(keyDBURL), errValueEmpty)
 		}
 
 		c.DBURL = fmt.Sprintf("file:%s/state.sqlite3?_journal_mode=WAL", c.StateDir)
@@ -356,6 +353,54 @@ func isKnownConfigKey(key string) bool {
 	return false
 }
 
+// envVarNames returns, for each configuration key, the environment
+// variable that also sets it: PIXA_ plus the key in upper case, with "."
+// written as "_", except the port, which REPO_POLICIES.md requires to be
+// PORT. metrics is set through its two subkeys; env has no variable.
+func envVarNames() map[string]string {
+	return map[string]string{ //nolint:gosec // G101: variable names, not secrets
+		keyDebug:                      "PIXA_DEBUG",
+		keyMaintenanceMode:            "PIXA_MAINTENANCE_MODE",
+		keyPort:                       "PORT",
+		keyStateDir:                   "PIXA_STATE_DIR",
+		keySentryDSN:                  "PIXA_SENTRY_DSN",
+		keyDBURL:                      "PIXA_DB_URL",
+		keyMetricsUsername:            "PIXA_METRICS_USERNAME",
+		keyMetricsPassword:            "PIXA_METRICS_PASSWORD",
+		keySigningKey:                 "PIXA_SIGNING_KEY",
+		keyAllowlistHosts:             "PIXA_ALLOWLIST_HOSTS",
+		keyAllowHTTP:                  "PIXA_ALLOW_HTTP",
+		keyUpstreamConnectionsPerHost: "PIXA_UPSTREAM_CONNECTIONS_PER_HOST",
+		keyCacheMaxBytes:              "PIXA_CACHE_MAX_BYTES",
+		keyBlockedNetworks:            "PIXA_BLOCKED_NETWORKS",
+		keyTrustedProxies:             "PIXA_TRUSTED_PROXIES",
+	}
+}
+
+// lookupValue returns the value set for key and whether one is set. The
+// key's environment variable wins when it is present, even when empty;
+// its value is a string, read exactly as the same text quoted in the
+// config file would be. Otherwise the config file's value is used.
+func lookupValue(sc *smartconfig.Config, key string) (any, bool) {
+	value, present := os.LookupEnv(envVarNames()[key])
+	if present {
+		return value, true
+	}
+
+	if sc == nil {
+		return nil, false
+	}
+
+	return sc.Get(key)
+}
+
+// settingName names key in an error message together with its
+// environment variable, since either one may have set the value.
+func settingName(key string) string {
+	return fmt.Sprintf("config key %q (environment variable %s)",
+		key, envVarNames()[key])
+}
+
 // ensureStateDirWritable verifies at startup that StateDir can be
 // created and written to, so a misconfigured path aborts startup
 // instead of failing later at first use.
@@ -364,28 +409,28 @@ func (c *Config) ensureStateDirWritable() error {
 
 	err := os.MkdirAll(c.StateDir, stateDirPerms)
 	if err != nil {
-		return fmt.Errorf("config key %q: cannot create directory %q: %w",
-			keyStateDir, c.StateDir, err)
+		return fmt.Errorf("%s: cannot create directory %q: %w",
+			settingName(keyStateDir), c.StateDir, err)
 	}
 
 	probe, err := os.CreateTemp(c.StateDir, ".startup-write-probe-*")
 	if err != nil {
-		return fmt.Errorf("config key %q: directory %q is not writable: %w",
-			keyStateDir, c.StateDir, err)
+		return fmt.Errorf("%s: directory %q is not writable: %w",
+			settingName(keyStateDir), c.StateDir, err)
 	}
 
 	probePath := probe.Name()
 
 	err = probe.Close()
 	if err != nil {
-		return fmt.Errorf("config key %q: cannot close probe file %q: %w",
-			keyStateDir, probePath, err)
+		return fmt.Errorf("%s: cannot close probe file %q: %w",
+			settingName(keyStateDir), probePath, err)
 	}
 
 	err = os.Remove(probePath)
 	if err != nil {
-		return fmt.Errorf("config key %q: cannot remove probe file %q: %w",
-			keyStateDir, probePath, err)
+		return fmt.Errorf("%s: cannot remove probe file %q: %w",
+			settingName(keyStateDir), probePath, err)
 	}
 
 	return nil
@@ -396,18 +441,19 @@ func (c *Config) ensureStateDirWritable() error {
 // key value itself is never echoed in error messages.
 func (c *Config) validateSigningKey() error {
 	if c.SigningKey == "" {
-		return fmt.Errorf("config key %q: %w", keySigningKey, errValueRequired)
+		return fmt.Errorf("%s: %w", settingName(keySigningKey), errValueRequired)
 	}
 
 	// Minimum key length for security (32 bytes = 256 bits)
 	const minKeyLength = 32
 	if len(c.SigningKey) < minKeyLength {
-		return fmt.Errorf("config key %q: %w: must be at least %d characters, got %d",
-			keySigningKey, errValueTooShort, minKeyLength, len(c.SigningKey))
+		return fmt.Errorf("%s: %w: must be at least %d characters, got %d",
+			settingName(keySigningKey), errValueTooShort, minKeyLength,
+			len(c.SigningKey))
 	}
 
 	if c.SigningKey == placeholderSigningKey {
-		return fmt.Errorf("config key %q: %w", keySigningKey, errPlaceholderKey)
+		return fmt.Errorf("%s: %w", settingName(keySigningKey), errPlaceholderKey)
 	}
 
 	return nil
@@ -423,25 +469,25 @@ func (c *Config) validate() error {
 
 	const maxPort = 65535
 	if c.Port < 1 || c.Port > maxPort {
-		return fmt.Errorf("config key %q: value %d is %w 1-%d",
-			keyPort, c.Port, errPortOutOfRange, maxPort)
+		return fmt.Errorf("%s: value %d is %w 1-%d",
+			settingName(keyPort), c.Port, errPortOutOfRange, maxPort)
 	}
 
 	if c.UpstreamConnectionsPerHost < 1 {
-		return fmt.Errorf("config key %q: value %d %w",
-			keyUpstreamConnectionsPerHost, c.UpstreamConnectionsPerHost,
-			errTooFewConnections)
+		return fmt.Errorf("%s: value %d %w",
+			settingName(keyUpstreamConnectionsPerHost),
+			c.UpstreamConnectionsPerHost, errTooFewConnections)
 	}
 
 	if c.StateDir == "" {
-		return fmt.Errorf("config key %q: %w", keyStateDir, errValueEmpty)
+		return fmt.Errorf("%s: %w", settingName(keyStateDir), errValueEmpty)
 	}
 
 	// Zero is valid (it disables the disk cache); only negative
 	// values are rejected. No floor applies to explicit values.
 	if c.CacheMaxBytes < 0 {
-		return fmt.Errorf("config key %q: value %d %w",
-			keyCacheMaxBytes, c.CacheMaxBytes, errMustNotBeNegative)
+		return fmt.Errorf("%s: value %d %w",
+			settingName(keyCacheMaxBytes), c.CacheMaxBytes, errMustNotBeNegative)
 	}
 
 	for _, host := range c.AllowlistHosts {
@@ -454,14 +500,15 @@ func (c *Config) validate() error {
 	if c.SentryDSN != "" {
 		parsed, err := url.Parse(c.SentryDSN)
 		if err != nil || parsed.Scheme == "" || parsed.Host == "" {
-			return fmt.Errorf("config key %q: value %q is %w",
-				keySentryDSN, c.SentryDSN, errNotAValidURL)
+			return fmt.Errorf("%s: value %q is %w",
+				settingName(keySentryDSN), c.SentryDSN, errNotAValidURL)
 		}
 	}
 
 	if (c.MetricsUsername == "") != (c.MetricsPassword == "") {
-		return fmt.Errorf("config keys %q and %q %w",
-			keyMetricsUsername, keyMetricsPassword, errMustBeSetTogether)
+		return fmt.Errorf("%s and %s %w",
+			settingName(keyMetricsUsername), settingName(keyMetricsPassword),
+			errMustBeSetTogether)
 	}
 
 	return nil
@@ -476,13 +523,13 @@ func (c *Config) validate() error {
 // disable URL signing.
 func validateAllowlistHost(host string) error {
 	if strings.Contains(host, "://") || strings.ContainsAny(host, "/ \t") {
-		return fmt.Errorf("config key %q: entry %q %w",
-			keyAllowlistHosts, host, errNotBareHostname)
+		return fmt.Errorf("%s: entry %q %w",
+			settingName(keyAllowlistHosts), host, errNotBareHostname)
 	}
 
 	if strings.Trim(host, ".") == "" {
-		return fmt.Errorf("config key %q: entry %q %w",
-			keyAllowlistHosts, host, errNoHostnameLabels)
+		return fmt.Errorf("%s: entry %q %w",
+			settingName(keyAllowlistHosts), host, errNoHostnameLabels)
 	}
 
 	return nil
@@ -598,11 +645,7 @@ func (l *strictLoader) boolVal(key string, defaultVal bool) bool {
 // is omitted. A present value that is not a string, or is explicitly
 // null, is an error.
 func getString(sc *smartconfig.Config, key, defaultVal string) (string, error) {
-	if sc == nil {
-		return defaultVal, nil
-	}
-
-	raw, ok := sc.Get(key)
+	raw, ok := lookupValue(sc, key)
 	if !ok {
 		return defaultVal, nil
 	}
@@ -624,11 +667,7 @@ func getString(sc *smartconfig.Config, key, defaultVal string) (string, error) {
 // omitted. A present value that is not a whole number, or is explicitly
 // null, is an error; fractional values are never truncated.
 func getInt(sc *smartconfig.Config, key string, defaultVal int) (int, error) {
-	if sc == nil {
-		return defaultVal, nil
-	}
-
-	raw, ok := sc.Get(key)
+	raw, ok := lookupValue(sc, key)
 	if !ok {
 		return defaultVal, nil
 	}
@@ -652,8 +691,8 @@ func getInt(sc *smartconfig.Config, key string, defaultVal int) (int, error) {
 	case string:
 		parsed, err := strconv.Atoi(strings.TrimSpace(val))
 		if err != nil {
-			return 0, fmt.Errorf("config key %q: value %q is %w",
-				key, val, errNotAnInteger)
+			return 0, fmt.Errorf("%s: value %q is %w",
+				settingName(key), val, errNotAnInteger)
 		}
 
 		return parsed, nil
@@ -668,11 +707,7 @@ func getInt(sc *smartconfig.Config, key string, defaultVal int) (int, error) {
 // is explicitly null, is an error; fractional values are never
 // truncated and out-of-range values are never clamped.
 func getInt64(sc *smartconfig.Config, key string, defaultVal int64) (int64, error) {
-	if sc == nil {
-		return defaultVal, nil
-	}
-
-	raw, ok := sc.Get(key)
+	raw, ok := lookupValue(sc, key)
 	if !ok {
 		return defaultVal, nil
 	}
@@ -703,8 +738,8 @@ func getInt64(sc *smartconfig.Config, key string, defaultVal int64) (int64, erro
 	case string:
 		parsed, err := strconv.ParseInt(strings.TrimSpace(val), 10, 64)
 		if err != nil {
-			return 0, fmt.Errorf("config key %q: value %q is %w",
-				key, val, errNotAnInteger)
+			return 0, fmt.Errorf("%s: value %q is %w",
+				settingName(key), val, errNotAnInteger)
 		}
 
 		return parsed, nil
@@ -719,11 +754,7 @@ func getInt64(sc *smartconfig.Config, key string, defaultVal int64) (int64, erro
 // string), or is explicitly null, is an error; numbers are not accepted
 // as booleans.
 func getBool(sc *smartconfig.Config, key string, defaultVal bool) (bool, error) {
-	if sc == nil {
-		return defaultVal, nil
-	}
-
-	raw, ok := sc.Get(key)
+	raw, ok := lookupValue(sc, key)
 	if !ok {
 		return defaultVal, nil
 	}
@@ -738,8 +769,8 @@ func getBool(sc *smartconfig.Config, key string, defaultVal bool) (bool, error)
 	case string:
 		parsed, err := strconv.ParseBool(strings.TrimSpace(val))
 		if err != nil {
-			return false, fmt.Errorf("config key %q: value %q is %w",
-				key, val, errNotABoolean)
+			return false, fmt.Errorf("%s: value %q is %w",
+				settingName(key), val, errNotABoolean)
 		}
 
 		return parsed, nil
@@ -755,7 +786,7 @@ func getBool(sc *smartconfig.Config, key string, defaultVal bool) (bool, error)
 // (or a comma-separated string), a non-string entry, or an empty entry
 // is an error, never silently skipped.
 func validateAllowlistHostsValue(sc *smartconfig.Config) error {
-	raw, ok := sc.Get(keyAllowlistHosts)
+	raw, ok := lookupValue(sc, keyAllowlistHosts)
 	if !ok {
 		return nil
 	}
@@ -785,8 +816,8 @@ func validateAllowlistHostsValue(sc *smartconfig.Config) error {
 
 		for part := range strings.SplitSeq(val, ",") {
 			if strings.TrimSpace(part) == "" {
-				return fmt.Errorf("config key %q: value %q %w",
-					keyAllowlistHosts, val, errEmptyEntry)
+				return fmt.Errorf("%s: value %q %w",
+					settingName(keyAllowlistHosts), val, errEmptyEntry)
 			}
 		}
 	default:
@@ -802,11 +833,7 @@ func validateAllowlistHostsValue(sc *smartconfig.Config) error {
 // comma-separated string (backwards compatibility). Malformed entries
 // are rejected beforehand by validateAllowlistHostsValue.
 func getStringSlice(sc *smartconfig.Config) []string {
-	if sc == nil {
-		return nil
-	}
-
-	val, ok := sc.Get(keyAllowlistHosts)
+	val, ok := lookupValue(sc, keyAllowlistHosts)
 	if !ok || val == nil {
 		return nil
 	}
@@ -866,11 +893,7 @@ func defaultTrustedProxies() []netip.Prefix {
 // aborts startup naming the key and the offending value; the default
 // (an empty list) applies only to an omitted key.
 func parseCIDRList(sc *smartconfig.Config, key string) ([]netip.Prefix, error) {
-	if sc == nil {
-		return nil, nil
-	}
-
-	raw, ok := sc.Get(key)
+	raw, ok := lookupValue(sc, key)
 	if !ok {
 		return nil, nil
 	}
@@ -889,8 +912,8 @@ func parseCIDRList(sc *smartconfig.Config, key string) ([]netip.Prefix, error) {
 	for _, entry := range entries {
 		prefix, err := netip.ParsePrefix(entry)
 		if err != nil {
-			return nil, fmt.Errorf("config key %q: value %q is %w",
-				key, entry, errNotAValidCIDR)
+			return nil, fmt.Errorf("%s: value %q is %w",
+				settingName(key), entry, errNotAValidCIDR)
 		}
 
 		prefixes = append(prefixes, prefix)
@@ -901,7 +924,8 @@ func parseCIDRList(sc *smartconfig.Config, key string) ([]netip.Prefix, error) {
 
 // cidrListEntries extracts the raw entries of the named CIDR-list key as
 // trimmed, non-empty strings, from either a YAML list of strings or a
-// comma-separated string. Any other shape is a configuration error.
+// comma-separated string; an empty string is an empty list, as for
+// allowlist_hosts. Any other shape is a configuration error.
 func cidrListEntries(raw any, key string) ([]string, error) {
 	switch val := raw.(type) {
 	case []any:
@@ -926,11 +950,15 @@ func cidrListEntries(raw any, key string) ([]string, error) {
 	case string:
 		entries := make([]string, 0)
 
+		if strings.TrimSpace(val) == "" {
+			return entries, nil
+		}
+
 		for part := range strings.SplitSeq(val, ",") {
 			trimmed := strings.TrimSpace(part)
 			if trimmed == "" {
-				return nil, fmt.Errorf("config key %q: value %q %w",
-					key, val, errEmptyEntry)
+				return nil, fmt.Errorf("%s: value %q %w",
+					settingName(key), val, errEmptyEntry)
 			}
 
 			entries = append(entries, trimmed)

internal/config/env_internal_test.go

@@ -0,0 +1,255 @@
+package config
+
+import (
+	"net/netip"
+	"os"
+	"reflect"
+	"slices"
+	"strings"
+	"testing"
+)
+
+// TestMain unsets PORT and every PIXA_ environment variable before the
+// tests run, so each test sees only the variables it sets itself, not
+// whatever the shell running the tests exports.
+func TestMain(m *testing.M) {
+	for _, entry := range os.Environ() {
+		name, _, _ := strings.Cut(entry, "=")
+		if name != "PORT" && !strings.HasPrefix(name, "PIXA_") {
+			continue
+		}
+
+		err := os.Unsetenv(name)
+		if err != nil {
+			panic(err)
+		}
+	}
+
+	m.Run()
+}
+
+// wantStartupError fails the test unless err is a startup error that
+// mentions every one of wants.
+func wantStartupError(t *testing.T, err error, wants ...string) {
+	t.Helper()
+
+	if err == nil {
+		t.Fatalf("want a startup error mentioning %q, got none", wants)
+	}
+
+	t.Logf("got expected error: %v", err)
+
+	for _, want := range wants {
+		if !strings.Contains(err.Error(), want) {
+			t.Errorf("error %q does not mention %q", err.Error(), want)
+		}
+	}
+}
+
+// TestEnvironmentSetsEveryKey sets every key from its environment
+// variable, with no config file at all: PORT for the port, and PIXA_
+// plus the key in upper case, "." written as "_", for every other key.
+func TestEnvironmentSetsEveryKey(t *testing.T) {
+	t.Setenv("PIXA_DEBUG", "true")
+	t.Setenv("PIXA_MAINTENANCE_MODE", "1")
+	t.Setenv("PORT", "9090")
+	t.Setenv("PIXA_STATE_DIR", "/srv/pixa-env")
+	t.Setenv("PIXA_SENTRY_DSN", "https://abc123@sentry.example.com/42")
+	t.Setenv("PIXA_DB_URL", "file:/srv/pixa-env/other.sqlite3")
+	t.Setenv("PIXA_METRICS_USERNAME", "metricsuser")
+	t.Setenv("PIXA_METRICS_PASSWORD", "metricspass")
+	t.Setenv("PIXA_SIGNING_KEY", validTestSigningKey)
+	t.Setenv("PIXA_ALLOWLIST_HOSTS", "s3.sneak.cloud,.example.com")
+	t.Setenv("PIXA_ALLOW_HTTP", "true")
+	t.Setenv("PIXA_UPSTREAM_CONNECTIONS_PER_HOST", "5")
+	t.Setenv("PIXA_CACHE_MAX_BYTES", "1024")
+	t.Setenv("PIXA_BLOCKED_NETWORKS", "203.0.113.0/24")
+	t.Setenv("PIXA_TRUSTED_PROXIES", "192.0.2.0/24")
+
+	c, err := newFromSmartConfig(nil)
+	if err != nil {
+		t.Fatalf("configuration from the environment alone should load: %v", err)
+	}
+
+	want := Config{
+		Debug:                      true,
+		MaintenanceMode:            true,
+		Port:                       9090,
+		StateDir:                   "/srv/pixa-env",
+		SentryDSN:                  "https://abc123@sentry.example.com/42",
+		DBURL:                      "file:/srv/pixa-env/other.sqlite3",
+		MetricsUsername:            "metricsuser",
+		MetricsPassword:            "metricspass",
+		SigningKey:                 validTestSigningKey,
+		AllowlistHosts:             []string{testHostS3, ".example.com"},
+		AllowHTTP:                  true,
+		UpstreamConnectionsPerHost: 5,
+		CacheMaxBytes:              1024,
+		cacheMaxBytesExplicit:      true,
+		BlockedNetworks:            []netip.Prefix{netip.MustParsePrefix("203.0.113.0/24")},
+		TrustedProxies:             []netip.Prefix{netip.MustParsePrefix("192.0.2.0/24")},
+	}
+
+	if !reflect.DeepEqual(*c, want) {
+		t.Errorf("config from the environment =\n%+v\nwant\n%+v", *c, want)
+	}
+}
+
+// TestPortFromEnvironmentOverridesConfigFile checks that PORT wins over
+// the port in the config file.
+func TestPortFromEnvironmentOverridesConfigFile(t *testing.T) {
+	t.Setenv("PORT", "9090")
+
+	c, err := configFromYAML(t, signingKeyLine+"port: 8080\n")
+	if err != nil {
+		t.Fatalf("PORT=9090 with port 8080 in the file should load: %v", err)
+	}
+
+	if c.Port != 9090 {
+		t.Errorf("Port = %d, want 9090 from PORT, not 8080 from the file", c.Port)
+	}
+}
+
+// TestInvalidPortFromEnvironmentAbortsStartup checks that a PORT that is
+// not a number, or is outside the port range, aborts startup naming PORT
+// and the value, even though the file's port is valid.
+func TestInvalidPortFromEnvironmentAbortsStartup(t *testing.T) {
+	t.Setenv("PORT", "banana")
+
+	_, err := configFromYAML(t, signingKeyLine+"port: 8080\n")
+	wantStartupError(t, err, "PORT", "banana")
+
+	t.Setenv("PORT", "70000")
+
+	_, err = configFromYAML(t, signingKeyLine+"port: 8080\n")
+	wantStartupError(t, err, "PORT", "70000")
+}
+
+// TestListFromEnvironmentReplacesConfigFileList checks that a list
+// variable replaces the file's list, split on commas with the spaces
+// around each entry trimmed.
+func TestListFromEnvironmentReplacesConfigFileList(t *testing.T) {
+	t.Setenv("PIXA_ALLOWLIST_HOSTS", " cdn.example.com , .example.org ")
+
+	c, err := configFromYAML(t, signingKeyLine+
+		"allowlist_hosts:\n  - s3.sneak.cloud\n  - sneak.berlin\n")
+	if err != nil {
+		t.Fatalf("PIXA_ALLOWLIST_HOSTS should load: %v", err)
+	}
+
+	want := []string{"cdn.example.com", ".example.org"}
+	if !slices.Equal(c.AllowlistHosts, want) {
+		t.Errorf("AllowlistHosts = %v, want %v from PIXA_ALLOWLIST_HOSTS",
+			c.AllowlistHosts, want)
+	}
+}
+
+// TestInvalidBlockedNetworksFromEnvironmentAbortsStartup checks that an
+// invalid CIDR, or an empty entry, in PIXA_BLOCKED_NETWORKS aborts
+// startup naming the variable, as the same list in the file does.
+func TestInvalidBlockedNetworksFromEnvironmentAbortsStartup(t *testing.T) {
+	t.Setenv("PIXA_BLOCKED_NETWORKS", "203.0.113.0/24,not-a-cidr")
+
+	_, err := configFromYAML(t, signingKeyLine)
+	wantStartupError(t, err, "PIXA_BLOCKED_NETWORKS", "not-a-cidr")
+
+	t.Setenv("PIXA_BLOCKED_NETWORKS", "203.0.113.0/24,,198.51.100.0/24")
+
+	_, err = configFromYAML(t, signingKeyLine)
+	wantStartupError(t, err, "PIXA_BLOCKED_NETWORKS")
+}
+
+// TestInvalidDebugFromEnvironmentAbortsStartup checks that a PIXA_DEBUG
+// that strconv.ParseBool rejects aborts startup instead of defaulting.
+func TestInvalidDebugFromEnvironmentAbortsStartup(t *testing.T) {
+	t.Setenv("PIXA_DEBUG", "maybe")
+
+	_, err := configFromYAML(t, signingKeyLine)
+	wantStartupError(t, err, "PIXA_DEBUG", "maybe")
+}
+
+// TestConfigFileAloneBehavesAsBefore checks that with no variables set
+// (TestMain unsets them) the config file's values are used and omitted
+// keys take their defaults.
+func TestConfigFileAloneBehavesAsBefore(t *testing.T) {
+	t.Parallel()
+
+	c, err := configFromYAML(t, signingKeyLine+"port: 9191\n")
+	if err != nil {
+		t.Fatalf("config file should load: %v", err)
+	}
+
+	if c.Port != 9191 {
+		t.Errorf("Port = %d, want 9191 from the file", c.Port)
+	}
+
+	if c.StateDir != DefaultStateDir {
+		t.Errorf("StateDir = %q, want default %q", c.StateDir, DefaultStateDir)
+	}
+
+	if !slices.Equal(c.TrustedProxies, defaultTrustedProxies()) {
+		t.Errorf("TrustedProxies = %v, want default %v",
+			c.TrustedProxies, defaultTrustedProxies())
+	}
+}
+
+// TestEmptyTrustedProxiesFromEnvironmentTrustsNoOne checks that an empty
+// PIXA_TRUSTED_PROXIES is an empty list, like [] in the file: it trusts
+// no proxy instead of taking the default ranges.
+func TestEmptyTrustedProxiesFromEnvironmentTrustsNoOne(t *testing.T) {
+	t.Setenv("PIXA_TRUSTED_PROXIES", "")
+
+	c, err := configFromYAML(t, signingKeyLine)
+	if err != nil {
+		t.Fatalf("empty PIXA_TRUSTED_PROXIES should load: %v", err)
+	}
+
+	if len(c.TrustedProxies) != 0 {
+		t.Errorf("TrustedProxies = %v, want none", c.TrustedProxies)
+	}
+}
+
+// TestEmptyVariableDoesNotFallBackToConfigFile checks that a variable
+// that is present but empty is a set value: an empty PIXA_STATE_DIR
+// aborts startup like state_dir: "" in the file, instead of falling
+// through to the file's state_dir.
+func TestEmptyVariableDoesNotFallBackToConfigFile(t *testing.T) {
+	t.Setenv("PIXA_STATE_DIR", "")
+
+	_, err := configFromYAML(t, signingKeyLine+"state_dir: /srv/pixa-file\n")
+	wantStartupError(t, err, "PIXA_STATE_DIR")
+}
+
+// TestMissingSigningKeyNamesItsVariable checks that with no config file
+// and no PIXA_SIGNING_KEY, startup aborts naming the variable, which is
+// how a container started without it reports the problem.
+func TestMissingSigningKeyNamesItsVariable(t *testing.T) {
+	t.Parallel()
+
+	_, err := newFromSmartConfig(nil)
+	wantStartupError(t, err, "PIXA_SIGNING_KEY")
+}
+
+// TestSecretsFromEnvironmentAreNotPrinted checks that errors about the
+// signing key and the metrics password name their variables but never
+// print their values.
+func TestSecretsFromEnvironmentAreNotPrinted(t *testing.T) {
+	t.Setenv("PIXA_SIGNING_KEY", "short-signing-secret")
+
+	_, err := newFromSmartConfig(nil)
+	wantStartupError(t, err, "PIXA_SIGNING_KEY")
+
+	if strings.Contains(err.Error(), "short-signing-secret") {
+		t.Errorf("error %q prints the signing key", err.Error())
+	}
+
+	t.Setenv("PIXA_SIGNING_KEY", validTestSigningKey)
+	t.Setenv("PIXA_METRICS_PASSWORD", "metrics-password-secret")
+
+	_, err = newFromSmartConfig(nil)
+	wantStartupError(t, err, "PIXA_METRICS_PASSWORD")
+
+	if strings.Contains(err.Error(), "metrics-password-secret") {
+		t.Errorf("error %q prints the metrics password", err.Error())
+	}
+}