feat: pass env variables through tesseract run and tesseract serve (#250)

#### Relevant issue or PR

@johnbcoughlin extracted this from #229 . It's needed right away and
requires less discussion, so makes sense to merge separately.

#### Description of changes
We allow passing user-defined env variables to docker (and
docker-compose) on `tesseract run` and `tesseract serve`.

Example:

```
tesseract run --env=MLFLOW_TRACKING_URI="http://localhost:5001" helloworld apply '...'
```

Immediately relevant use case: Connecting tesseracts to user-hosted
MLflow servers.

#### Testing done
Tested manually.

---------

Co-authored-by: Jack Coughlin <jack@johnbcoughlin.com>
Co-authored-by: Alessandro Angioi <alessandro.angioi@simulation.science>
Co-authored-by: Dion Häfner <dion.haefner@simulation.science>

Author: 4 people

.github/workflows/run_tests.yml

@@ -114,7 +114,8 @@ jobs:
             --skip-endtoend \
             --cov-report=term-missing:skip-covered \
             --cov-report=xml:coverage.xml \
-            --cov=tesseract_core
+            --cov=tesseract_core \
+            --cov-branch
 
       - name: Run test suite (Windows)
         if: runner.os == 'Windows'
@@ -125,7 +126,8 @@ jobs:
             --skip-endtoend \
             --cov-report=term-missing:skip-covered \
             --cov-report=xml:coverage.xml \
-            --cov=tesseract_core
+            --cov=tesseract_core \
+            --cov-branch
 
       - name: Upload coverage reports to Codecov
         uses: codecov/codecov-action@v5.4.3
@@ -279,6 +281,7 @@ jobs:
           if [ "${{ matrix.unit-tesseract }}" == "base" ]; then
             uv run --no-sync pytest \
               --always-run-endtoend \
+              --cov-branch \
               --cov-report=term-missing:skip-covered \
               --cov-report=xml:coverage.xml \
               --cov=tesseract_core \
@@ -287,6 +290,7 @@ jobs:
           else
             uv run --no-sync pytest \
               --always-run-endtoend \
+              --cov-branch \
               --cov-report=term-missing:skip-covered \
               --cov-report=xml:coverage.xml \
               --cov=tesseract_core \

docs/content/using-tesseracts/advanced.md

@@ -16,6 +16,16 @@ target path:
 $ tesseract run vectoradd apply --output-path /tmp/output @inputs.json
 ```
 
+## Passing environment variables to Tesseract containers
+
+Through the optional `--env` argument, you can pass environment variables to Tesseracts.
+This works both for serving a Tesseract and running a single execution:
+
+```bash
+$ tesseract serve --env=MY_ENV_VARIABLE="some value" helloworld
+$ tesseract run --env=MY_ENV_VARIABLE="some value" helloworld apply '{"inputs": {"name": "Osborne"}}'
+```
+
 ## Using GPUs
 
 To leverage GPU support in your Tesseract environment, you can specify which NVIDIA GPU(s) to make available

tesseract_core/sdk/cli.py

@@ -436,6 +436,14 @@ def serve(
             show_default=False,
         ),
     ] = None,
+    environment: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--env",
+            "-e",
+            help="Set environment variables in the Tesseract containers, in Docker format: key=value.",
+        ),
+    ] = None,
     port: Annotated[
         str | None,
         typer.Option(
@@ -542,6 +550,19 @@ def serve(
     else:
         ports = None
 
+    # Parse environment variables from list to dict
+    if environment is not None:
+        try:
+            environment = {
+                env.split("=", maxsplit=1)[0]: env.split("=", maxsplit=1)[1]
+                for env in environment
+            }
+        except Exception as ex:
+            raise typer.BadParameter(
+                "Environment variables must be in the format 'key=value'.",
+                param_hint="environment",
+            ) from ex
+
     if service_names is not None:
         if no_compose:
             raise typer.BadParameter(
@@ -559,6 +580,7 @@ def serve(
             host_ip,
             ports,
             volume,
+            environment,
             gpus,
             debug,
             num_workers,
@@ -840,6 +862,16 @@ def run_container(
             ),
         ),
     ] = None,
+    environment: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--env",
+            "-e",
+            help="Set environment variables in the Tesseract container, in Docker format: key=value.",
+            metavar="key=value",
+            show_default=False,
+        ),
+    ] = None,
     user: Annotated[
         str | None,
         typer.Option(
@@ -888,9 +920,26 @@ def run_container(
         )
         raise typer.BadParameter(error_string, param_hint="cmd")
 
+    if environment is not None:
+        try:
+            environment = {
+                item.split("=", maxsplit=1)[0]: item.split("=", maxsplit=1)[1]
+                for item in environment
+            }
+        except Exception as ex:
+            raise typer.BadParameter(
+                "Environment variables must be in the format 'key=value'.",
+                param_hint="env",
+            ) from ex
     try:
         result_out, result_err = engine.run_tesseract(
-            tesseract_image, cmd, args, volumes=volume, gpus=gpus, user=user
+            tesseract_image,
+            cmd,
+            args,
+            volumes=volume,
+            gpus=gpus,
+            environment=environment,
+            user=user,
         )
 
     except ImageNotFound as e:

tesseract_core/sdk/docker_client.py

@@ -507,6 +507,7 @@ def run(
         command: list_[str],
         volumes: dict | None = None,
         device_requests: list_[int | str] | None = None,
+        environment: dict[str, str] | None = None,
         detach: bool = False,
         remove: bool = False,
         ports: dict | None = None,
@@ -565,6 +566,12 @@ def run(
             gpus_str = ",".join(device_requests)
             optional_args.extend(["--gpus", f'"device={gpus_str}"'])
 
+        if environment:
+            env_args = []
+            for env_var, value in environment.items():
+                env_args.extend(["-e", f"{env_var}={value}"])
+            optional_args.extend(env_args)
+
         # Remove and detached cannot both be set to true
         if remove and detach:
             raise ValueError(

tesseract_core/sdk/engine.py

@@ -544,6 +544,7 @@ def serve(
     host_ip: str = "127.0.0.1",
     ports: list[str] | None = None,
     volumes: list[str] | None = None,
+    environment: dict[str, str] | None = None,
     gpus: list[str] | None = None,
     debug: bool = False,
     num_workers: int = 1,
@@ -560,6 +561,7 @@ def serve(
         host_ip: IP address to bind the Tesseracts to.
         ports: port or port range to serve each Tesseract on.
         volumes: list of paths to mount in the Tesseract container.
+        environment: dictionary of environment variables to pass to the Tesseract.
         gpus: IDs of host Nvidia GPUs to make available to the Tesseracts.
         debug: Enable debug mode. This will propagate full tracebacks to the client
             and start a debugpy server in the Tesseract.
@@ -671,6 +673,7 @@ def serve(
         service_names,
         ports,
         volumes,
+        environment,
         gpus,
         num_workers,
         debug=debug,
@@ -697,6 +700,7 @@ def _create_docker_compose_template(
     service_names: list[str] | None = None,
     ports: list[str] | None = None,
     volumes: list[str] | None = None,
+    environment: dict[str, str] | None = None,
     gpus: list[str] | None = None,
     num_workers: int = 1,
     debug: bool = False,
@@ -756,6 +760,7 @@ def _create_docker_compose_template(
             "gpus": gpu_settings,
             "environment": {
                 "TESSERACT_DEBUG": "1" if debug else "0",
+                **(environment or {}),
             },
             "num_workers": num_workers,
             "debugpy_port": debugpy_ports[i] if debug else None,
@@ -843,6 +848,7 @@ def run_tesseract(
     volumes: list[str] | None = None,
     gpus: list[int | str] | None = None,
     ports: dict[str, str] | None = None,
+    environment: dict[str, str] | None = None,
     user: str | None = None,
 ) -> tuple[str, str]:
     """Start a Tesseract and execute a given command.
@@ -855,6 +861,8 @@ def run_tesseract(
         gpus: list of GPUs, as indices or names, to passthrough the container.
         ports: dictionary of ports to bind to the host. Key is the host port,
             value is the container port.
+        environment: list of environment variables to set in the container,
+            in Docker format: key=value.
         user: user to run the Tesseract as, e.g. '1000' or '1000:1000' (uid:gid).
 
     Returns:
@@ -920,6 +928,7 @@ def run_tesseract(
         command=cmd,
         volumes=parsed_volumes,
         device_requests=gpus,
+        environment=environment,
         ports=ports,
         detach=False,
         remove=True,

tesseract_core/sdk/tesseract.py

@@ -26,6 +26,7 @@ class SpawnConfig:
 
     image: str
     volumes: list[str] | None
+    environment: dict[str, str] | None
     gpus: list[str] | None
     num_workers: int
     debug: bool
@@ -84,6 +85,7 @@ def from_image(
         image: str,
         *,
         volumes: list[str] | None = None,
+        environment: dict[str, str] | None = None,
         gpus: list[str] | None = None,
         num_workers: int = 1,
         no_compose: bool = False,
@@ -104,6 +106,7 @@ def from_image(
         Args:
             image: The Docker image to use.
             volumes: List of volumes to mount, e.g. ["/path/on/host:/path/in/container"].
+            environment: dictionary of environment variables to pass to the Tesseract.
             gpus: List of GPUs to use, e.g. ["0", "1"]. (default: no GPUs)
             num_workers: Number of worker processes to use. This determines how
                 many requests can be handled in parallel. Higher values
@@ -117,6 +120,7 @@ def from_image(
         obj._spawn_config = SpawnConfig(
             image=image,
             volumes=volumes,
+            environment=environment,
             gpus=gpus,
             num_workers=num_workers,
             debug=True,
@@ -223,6 +227,7 @@ def serve(self, port: str | None = None, host_ip: str = "127.0.0.1") -> None:
             self._spawn_config.image,
             port=port,
             volumes=self._spawn_config.volumes,
+            environment=self._spawn_config.environment,
             gpus=self._spawn_config.gpus,
             num_workers=self._spawn_config.num_workers,
             debug=self._spawn_config.debug,
@@ -265,6 +270,7 @@ def _serve(
         port: str | None = None,
         host_ip: str = "127.0.0.1",
         volumes: list[str] | None = None,
+        environment: dict[str, str] | None = None,
         gpus: list[str] | None = None,
         debug: bool = False,
         num_workers: int = 1,
@@ -279,6 +285,7 @@ def _serve(
             [image],
             ports=ports,
             volumes=volumes,
+            environment=environment,
             gpus=gpus,
             debug=debug,
             num_workers=num_workers,

tests/endtoend_tests/test_endtoend.py

@@ -5,6 +5,7 @@
 
 import json
 import os
+import subprocess
 from pathlib import Path
 
 import pytest
@@ -128,6 +129,33 @@ def test_build_generate_only(dummy_tesseract_location, skip_checks):
             assert 'RUN ["tesseract-runtime", "check"]' in docker_file_contents
 
 
+def test_env_passthrough_serve(docker_cleanup, docker_client, built_image_name):
+    """Ensure we can pass environment variables to tesseracts when serving."""
+    run_res = subprocess.run(
+        [
+            "tesseract",
+            "serve",
+            built_image_name,
+            "--env=TEST_ENV_VAR=foo",
+        ],
+        capture_output=True,
+        text=True,
+    )
+    assert run_res.returncode == 0, run_res.stderr
+    assert run_res.stdout
+
+    project_meta = json.loads(run_res.stdout)
+    project_id = project_meta["project_id"]
+    tesseract_id = project_meta["containers"][0]["name"]
+
+    docker_cleanup["project_ids"].append(project_id)
+
+    container = docker_client.containers.get(tesseract_id)
+    exit_code, output = container.exec_run(["sh", "-c", "echo $TEST_ENV_VAR"])
+    assert exit_code == 0, f"Command failed with exit code {exit_code}"
+    assert "foo" in output.decode("utf-8"), f"Output was: {output.decode('utf-8')}"
+
+
 def test_tesseract_list(built_image_name):
     # Test List Command
     cli_runner = CliRunner(mix_stderr=False)

tests/sdk_tests/test_tesseract.py

@@ -116,6 +116,7 @@ def test_serve_lifecycle(mock_serving, mock_clients):
         ["sometesseract:0.2.3"],
         ports=None,
         volumes=None,
+        environment=None,
         gpus=None,
         debug=True,
         num_workers=1,