Forward host environment variables to the rollups node container

[tuler]

📚 Context

The rollups node supports fine-grained configuration through environment variables that the CLI does not expose as flags. For example, CARTESI_LOG_LEVEL_JSONRPC_API controls the log level of the JSON-RPC API subsystem independently of the global CARTESI_LOG_LEVEL.

Today there is no way to set such a variable through the CLI. Defining it in the shell when running cartesi run has no effect:

CARTESI_LOG_LEVEL_JSONRPC_API=debug cartesi run
# variable is not present in the rollups_node container

The reason is that the environment passed to docker compose (in startEnvironment at apps/cli/src/exec/rollups.ts) only reaches the compose client process — execa already merges process.env by default (extendEnv: true). Docker Compose does not forward its own process environment into containers: a container's environment comes solely from the environment: / env_file: sections of the compose file. The host-side environment is only used for ${VAR} interpolation in the YAML and for valueless passthrough keys (e.g. - FOO). The compose services generated by the CLI (e.g. apps/cli/src/compose/node.ts) define fully literal environment: maps, with no interpolation and no passthrough keys — so nothing from the user's shell can reach the containers.

✔️ Solution

Possible approaches (not mutually exclusive):

1. Prefix passthrough: in startEnvironment, collect all CARTESI_* variables from process.env and inject them into the rollups_node service environment: section.
   • Benefit: zero ceremony, works for any current and future node variable.
   • Drawback: ambient shell variables silently affect the node; precedence must be defined (should a shell CARTESI_LOG_LEVEL override the value derived from --verbose?).
2. Explicit flag: add --env KEY=VALUE (repeatable) to cartesi run.
   • Benefit: explicit and discoverable, no ambient-environment surprises.
   • Drawback: more typing for something the user already expressed as an env var.
3. Project config: support an env section in cartesi.toml for persistent per-project node configuration.
   • Benefit: declarative and versionable.
   • Drawback: not suited for one-off overrides.

📈 Subtasks

• Decide approach and precedence rules (CLI-flag-derived values vs user-provided values)
• Implement forwarding in startEnvironment / compose generation
• Add tests covering the generated compose output (--dry-run config)
• Document the behavior

🎯 Definition of Done

• CARTESI_LOG_LEVEL_JSONRPC_API=debug cartesi run (or the equivalent flag/config) results in the variable being set inside the rollups_node container

[brunomenezes]

@tuler , I am not sure about closing that issue after implementing the pass-through approach (with a strict allowed list) if the other approaches are desirable. Nonetheless, I coded in a way that the overrides precedence can be easily added as follows: explicit flag (one off runs) > project config (e.g. cartesi.toml) > host env vars > defaults defined internally

Here is the line that makes that precedence ready: compose/node.ts