Configure backbeat from the environment, without rewriting the config file

.github/copilot-instructions.md

@@ -7,15 +7,15 @@ Repo context lives in [CLAUDE.md](../CLAUDE.md) — read it first.
 When reviewing a PR, analyze the changes against these criteria:
 
 | Area | What to check |
-|------|---------------|
+| ------ | --------------- |
 | Async error handling | Uncaught promise rejections, missing error callbacks, swallowed errors in streams. Double callbacks in try/catch blocks (callback called in try then again in catch) |
 | Async/await usage | New or modified code should use async/await instead of callbacks (see [Async/await migration suggestions](#asyncawait-migration-suggestions) below for when to suggest migrating). When code is migrated from callbacks to async/await, verify: no leftover callback or next params, no mixed callback + promise patterns, proper try/catch around awaited calls, errors are re-thrown or handled (not silently swallowed), `return await` rather than returning a bare promise, no `forEach` with async callbacks (use `for...of` or `Promise.all`), callers updated or backward compatibility kept via `util.callbackify`. Watch for the anti-pattern: `try { cb(); } catch(err) { cb(err); }` where an exception after the first `cb()` triggers a second call |
 | Kafka consumer/producer | Correct topic configuration, proper offset commits, consumer group handling, message serialization. Verify `onEntryCommittable` is always reachable. Check circuit breaker thresholds when adding new downstream topics |
 | Stream handling | Backpressure, proper cleanup on error, no leaked file descriptors, correct pipe chains |
 | Dependency pinning | Git-based deps (arsenal, vaultclient, bucketclient, werelogs, breakbeat, httpagent) must pin to a tag, not a branch |
 | Logging | Proper use of werelogs, no `console.log` in production code, log levels match severity. Include enough context (bucket, object key, version, offset) for production troubleshooting |
 | Prometheus metrics | New metrics follow existing naming conventions (`s3_backbeat_*`), correct metric types (counter vs gauge vs histogram), bounded label cardinality — avoid per-connector or per-bucket labels that explode with scale |
-| Config changes | Backward compatibility, Joi schema updates match new fields, environment variable naming, default values. Env var overrides in `lib/Config.js` must stay consistent with the config file schema |
+| Config changes | Backward compatibility, Joi schema updates match new fields, environment variable naming, default values. New setting preferably belong in the joi schema, which derives its env var: flag a raw `process.env` read, or hand-rolled parsing, where a schema field or a meta annotation would do. Any deviation / custom configuration via env variable must be documented in `docs/configuration.md` in the same commit. |
 | MongoDB / Redis resilience | Reconnection handling, proper timeouts on external calls, no indefinite waits. Network errors to MongoDB must not cause stuck tasks or silent data loss |
 | Extension architecture | Changes respect the pluggable extension pattern, no cross-extension coupling |
 | Security | Command injection, prototype pollution, unsafe deserialization, credential exposure in config/env vars, OWASP-relevant issues for Node.js |

CLAUDE.md

@@ -13,6 +13,16 @@ This is a **Node.js asynchronous queue and job manager** for Scality's S3C and A
 - CommonJS modules; legacy code is callback-based, migrating to async/await (see below)
 - Mocha + Sinon test suites (`tests/unit/`, `tests/functional/`, `tests/behavior/`)
 
+## Configuration
+
+Every configuration field is settable from the environment, with the variable name derived from the joi schema — see [docs/configuration.md](docs/configuration.md):
+
+- Add a setting by declaring it in the joi schema (`lib/config.joi.js`, `lib/config/configItems.joi.js`, or the extension's own validator). The env var follows from the config path, so nothing else is needed, and the value is validated.
+- Do not read `process.env` directly for something the configuration could hold, and do not
+  hand-roll parsing: prefer a schema field, an `env`/`envVarAlias` annotation to adjust variable
+  name, or an `envDecodeHook` for custom decoding of the value.
+- Anything that escapes that path — a variable read straight from `process.env`, one setting several fields, or a decode hook — is invisible to the schema, so document it in [docs/configuration.md](docs/configuration.md) in the same change, and cover it with a test.
+
 ## Async code style
 
 The codebase is migrating from callbacks and the `async` library to async/await, per the [Scality migration guide](https://scality.atlassian.net/wiki/spaces/OS/pages/3523346468/2025-10-30+-+Async+Await+migration):

Dockerfile

@@ -14,7 +14,6 @@ RUN apt-get update \
         bash \
         python3 \
         git \
-        jq \
         zlib1g-dev \
         libncurses5-dev \
         libgdbm-dev \
@@ -45,7 +44,6 @@ FROM node:${NODE_VERSION}
 RUN apt-get update && \
     apt-get install -y --no-install-recommends \
         ca-certificates \
-        jq \
         krb5-user \
         libsasl2-2 \
         libsasl2-modules-gssapi-mit \
@@ -62,6 +60,6 @@ COPY --from=builder /usr/local/bin/dockerize /usr/local/bin/
 
 ENV AWS_SDK_JS_SUPPRESS_MAINTENANCE_MODE_MESSAGE=1
 
-ENTRYPOINT ["tini", "-g", "--", "/usr/src/app/docker-entrypoint.sh"]
+ENTRYPOINT ["tini", "-g", "--"]
 
 EXPOSE 8900

README.md

@@ -27,6 +27,7 @@ updates in a FIFO order.
 ## DESIGN
 
 - [Backbeat core design](/DESIGN.md)
+- [Configuration](/docs/configuration.md)
 - [CRR to AWS S3 workflow](/docs/crr-to-aws-s3.md)
 - [Object Lifecycle management](/docs/lifecycle.md)
 - [Metrics](/docs/metrics.md)