From 0bc9c21c2b9ecc7a74a30ba45b21ea075630cd53 Mon Sep 17 00:00:00 2001 From: Ankur Shrivastava Date: Mon, 4 May 2026 23:46:43 +0800 Subject: [PATCH] docs: surface dual-loader support (envconfig + env-tag) on framework pages MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The framework Config struct carries both envconfig: and env: struct tags on every field, but the docs only mentioned envconfig — hiding the interop story from users of caarlos0/env, sethvargo/go-envconfig, ilyakaznacheev/cleanenv, and similar env:-tag loaders. - config-reference.md: full dual-loader phrasing with three loader examples - Packages.md, FAQ.md, architecture.md: shorter mention of compatible env:-tag loaders alongside envconfig - howto/APIs.md: drop orphaned [envconfig] reference link def (no body usage) Howto pages that show users adding fields to their own AppConfig (database/cache/messaging) are intentionally untouched — those examples should still use a single tag matching whichever loader the user chooses. --- FAQ.md | 2 +- Packages.md | 2 +- architecture.md | 2 +- config-reference.md | 2 +- howto/APIs.md | 1 - 5 files changed, 4 insertions(+), 5 deletions(-) diff --git a/FAQ.md b/FAQ.md index f4b2f54..1dcdc90 100644 --- a/FAQ.md +++ b/FAQ.md @@ -211,7 +211,7 @@ Yes — ColdBrew is Kubernetes-native by design. Out of the box you get: - **Graceful shutdown** on SIGTERM with configurable drain periods (`SHUTDOWN_DURATION_IN_SECONDS`, `GRPC_GRACEFUL_DURATION_IN_SECONDS`) - **Prometheus metrics** at `/metrics` for scraping - **Structured JSON logging** to stdout (ready for Fluentd, Loki, or any log aggregator) -- **Environment variable configuration** via [envconfig](https://github.com/kelseyhightower/envconfig) — works natively with ConfigMaps and Secrets +- **Environment variable configuration** via [envconfig](https://github.com/kelseyhightower/envconfig) or any `env:`-tag loader (e.g. [caarlos0/env](https://github.com/caarlos0/env)) — works natively with ConfigMaps and Secrets ColdBrew also follows [12-factor app](https://12factor.net/) principles: no config files, stateless processes, port binding, and log streams. See the [Production Deployment guide](/howto/production) for K8s manifests, ServiceMonitor setup, and graceful shutdown tuning, and the [Architecture](/architecture) page for the full design principles table. diff --git a/Packages.md b/Packages.md index c9a5a3a..02f3a27 100644 --- a/Packages.md +++ b/Packages.md @@ -20,7 +20,7 @@ The core module is the base module and provides the base implementation for Cold Documentation can be found at [core-docs] ### [Config] -ColdBrew config package contains the configuration for the core package. It uses [envconfig] to load the configuration from the environment variables. +ColdBrew config package contains the configuration for the core package. Each field carries both `envconfig:"…"` and `env:"…"` struct tags, so it can be loaded with [envconfig] (the cookiecutter default) or any `env:`-tag loader such as [caarlos0/env](https://github.com/caarlos0/env). Documentation can be found at [config-docs] diff --git a/architecture.md b/architecture.md index 436b2a0..4808d60 100644 --- a/architecture.md +++ b/architecture.md @@ -22,7 +22,7 @@ ColdBrew follows [12-factor app](https://12factor.net/) methodology and is desig | 12-Factor Principle | How ColdBrew Implements It | |--------------------|-----------------------------| -| **Config** | All configuration via environment variables ([envconfig](https://github.com/kelseyhightower/envconfig)) — no config files, no YAML. See [Configuration Reference](/config-reference) | +| **Config** | All configuration via environment variables — works with [envconfig](https://github.com/kelseyhightower/envconfig) or any `env:`-tag loader like [caarlos0/env](https://github.com/caarlos0/env). No config files, no YAML. See [Configuration Reference](/config-reference) | | **Port binding** | Self-contained HTTP (`:9091`) and gRPC (`:9090`) servers, optional dedicated admin port (`ADMIN_PORT`) for endpoint isolation | | **Logs** | Structured JSON to stdout by default — ready for any log aggregator (Fluentd, Loki, CloudWatch) | | **Disposability** | Graceful SIGTERM handling with configurable drain periods. See [Signals](/howto/signals) | diff --git a/config-reference.md b/config-reference.md index 7a08553..7d9fcd5 100644 --- a/config-reference.md +++ b/config-reference.md @@ -16,7 +16,7 @@ permalink: /config-reference --- -ColdBrew is configured entirely through environment variables using [envconfig](https://github.com/kelseyhightower/envconfig). All fields have sensible defaults — you can run a service with zero configuration. +ColdBrew is configured entirely through environment variables. The framework `Config` struct carries both `envconfig:"…"` and `env:"…"` struct tags, so services can populate it with [kelseyhightower/envconfig](https://github.com/kelseyhightower/envconfig) (the cookiecutter default) or any `env:`-tag loader such as [caarlos0/env](https://github.com/caarlos0/env), [sethvargo/go-envconfig](https://github.com/sethvargo/go-envconfig), or [ilyakaznacheev/cleanenv](https://github.com/ilyakaznacheev/cleanenv). All fields have sensible defaults — you can run a service with zero configuration. Access the config in code via: diff --git a/howto/APIs.md b/howto/APIs.md index fcbdf0a..f4be50c 100644 --- a/howto/APIs.md +++ b/howto/APIs.md @@ -765,7 +765,6 @@ Benchmark source: [`benchmarks/`](https://github.com/go-coldbrew/core/tree/main/ [google/rpc/code.proto]: https://github.com/googleapis/googleapis/blob/master/google/rpc/code.proto [ColdBrew errors package]: https://pkg.go.dev/github.com/go-coldbrew/errors#NewWithStatus [errors package]: https://pkg.go.dev/github.com/go-coldbrew/errors -[envconfig]: https://github.com/kelseyhightower/envconfig [ColdBrew]: https://docs.coldbrew.cloud ## Related