Container-Friendly Secrets: Make endpoint, auth, and DB settings work with Docker / Compose / Kubernetes secrets

[vfusco]

Context / Problem

Teams routinely deploy Rollups-Node services in containers, but several critical variables still force operators to embed secrets directly in the environment:

• CARTESI_BLOCKCHAIN_HTTP_ENDPOINT — typically contains an Infura project ID, e.g. https://mainnet.infura.io/v3/<YOUR-API-KEY>.
• Authentication variables — private keys, mnemonics, or AWS KMS IDs.
• CARTESI_DATABASE_CONNECTION — full Postgres URI with password.

Plain-text env vars clash with best practices for:

• Docker Compose secrets – see Docker docs (how-to, compose-file).
• Kubernetes secrets – see the official guide (https://kubernetes.io/docs/concepts/configuration/secret/).

Without proper support, operators must bake tokens into images or manifests, making rotation and auditing painful.

---

Suggested Solution

1. *_FILE convention for secret-bearing vars

   • For every variable that may contain a secret, recognise a sibling var ending in _FILE.
     • Examples: CARTESI_BLOCKCHAIN_HTTP_ENDPOINT_FILE, CARTESI_AUTH_PRIVATE_KEY_FILE, CARTESI_DATABASE_CONNECTION_FILE, etc.
   • If the primary var is unset and the file variant is set, read the file’s content (trim newline) at start-up.
   • Mirrors the convention used by many official Docker images.

2. Split token/header helpers for blockchain endpoints

   • Accept an alternative split form:
     • CARTESI_BLOCKCHAIN_HTTP_ENDPOINT_BASE=https://mainnet.infura.io/v3
     • CARTESI_BLOCKCHAIN_HTTP_TOKEN_FILE=/run/secrets/infura_project_id
   • At runtime, synthesise the final URL (https://mainnet.infura.io/v3/<token>).
   • Optionally support CARTESI_BLOCKCHAIN_HTTP_HEADERS (comma-separated Header:Value) for providers that require Bearer headers instead of path tokens.

3. Postgres connection helpers

   • Support _FILE as above.
   • Optionally parse separate vars (PGHOST, PGUSER, PGDATABASE, PGPASSWORD_FILE, …) if CARTESI_DATABASE_CONNECTION is absent, matching the Postgres container pattern.

4. Precedence & validation

   • Priority: explicit var > _FILE var > split/base+token form > driver defaults.
   • Fail fast with clear errors if both var and var_FILE are set inconsistently.

5. Logging hygiene

   • Redact any value sourced via a _FILE path when printing configuration at start-up.

---

Deliverables

• Config loader update shared by claimer, node, cli, validator, etc.
• Unit tests for _FILE handling, precedence, and redaction.
• docker-compose example:
  • Infura project ID, private key, and DB password mounted as secrets files.
• Kubernetes snippet:
  • Deployment YAML using valueFrom: secretKeyRef.
• Documentation in “Running in Containers” with cross-links to:
  • Docker Compose secrets how-to.
  • Docker compose-file secrets reference.
  • Kubernetes secrets overview.

---

Acceptance Criteria

#	Scenario	Expected outcome
1	Service started with CARTESI_BLOCKCHAIN_HTTP_ENDPOINT_FILE	Connects using file content; token never appears in logs
2	docker-compose stack mounts secrets files	Services start without plain-text secrets in docker inspect
3	Kubernetes deployment uses secretKeyRef	Pods start; container logs show redacted config lines
4	Both VAR and VAR_FILE set inconsistently	Service exits with clear precedence error
5	AWS KMS auth via _FILE vars	Transactions are signed; no secrets leak to stdout

By adopting the standard _FILE pattern and split-token helpers, Rollups-Node becomes a good citizen in Docker, Compose, and Kubernetes environments—keeping credentials out of images, manifests, and logs.

[vfusco]

Suggested by @endersonmaia

[endersonmaia]

About postgres credentials see #55