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)