feat: Add ability to configure host IP during tesseract serve (#185)

#### Relevant issue or PR
n/a

#### Description of changes
- Serve on `127.0.0.1` (localhost) by default when using
`tesseract-runtime serve`, to avoid accidentally exposing Tesseracts to
the local or public internet when using `tesseract-runtime` directly.
- Add capability to configure host IP when serving containers via
`tesseract serve`.

To-do:
- [x] Also expose in Python API
- [x] Add tests

#### Testing done
CI + manual

Author: dionhaefner

docs/content/introduction/get-started.md

@@ -45,15 +45,15 @@ $ tesseract serve -p 8080 helloworld
  [i] Container ID: 2587deea2a2efb6198913f757772560d9c64cf8621a6d1a54aa3333a7b4bcf62
  [i] Name: tesseract-uum375qt6dj5-sha256-9by9ahsnsza2-1
  [i] Entrypoint: ['tesseract-runtime', 'serve']
- [i] View Tesseract: http://localhost:56489/docs
+ [i] View Tesseract: http://127.0.0.1:56489/docs
  [i] Docker Compose Project ID, use it with 'tesseract teardown' command: tesseract-u7um375qt6dj5
 {"project_id": "tesseract-u7um375qt6dj5", "containers": [{"name": "tesseract-uum375qt6dj5-sha256-9by9ahsnsza2-1", "port": "8080"}]}%
 
 $ # The port at which your Tesseract will be served is random if `--port` is not specified;
 $ # specify the one you received from `tesseract serve` output in the next command.
 $ curl -d '{"inputs": {"name": "Osborne"}}' \
        -H "Content-Type: application/json" \
-       http://localhost:8080/apply
+       http://127.0.0.1:8080/apply
 {"greeting":"Hello Osborne!"}
 
 $ tesseract teardown tesseract-9hj8fyxrx073
@@ -86,7 +86,7 @@ $ tesseract run helloworld --help
 ```bash
 $ tesseract apidoc helloworld
  [i] Waiting for Tesseract containers to start ...
- [i] Serving OpenAPI docs for Tesseract helloworld at http://localhost:59569/docs
+ [i] Serving OpenAPI docs for Tesseract helloworld at http://127.0.0.1:59569/docs
  [i]   Press Ctrl+C to stop
 ```
 :::

tesseract_core/runtime/cli.py

@@ -309,7 +309,7 @@ def check_gradients(
 
 @tesseract_runtime.command()
 @click.option("-p", "--port", default=8000, help="Port number")
-@click.option("-h", "--host", default="0.0.0.0", help="Host IP address")
+@click.option("-h", "--host", default="127.0.0.1", help="Host IP address")
 @click.option("-w", "--num-workers", default=1, help="Number of worker processes")
 def serve(host: str, port: int, num_workers: int) -> None:
     """Start running this Tesseract's web server."""

tesseract_core/sdk/cli.py

@@ -417,6 +417,17 @@ def serve(
             callback=_validate_port,
         ),
     ] = None,
+    host_ip: Annotated[
+        str,
+        typer.Option(
+            "--host-ip",
+            help=(
+                "IP address of the host to bind the Tesseract to. "
+                "Defaults to 127.0.0.1 (localhost). To bind to all interfaces, use '0.0.0.0'. "
+                "WARNING: This may expose Tesseract to all local networks, use with caution."
+            ),
+        ),
+    ] = "127.0.0.1",
     gpus: Annotated[
         list[str] | None,
         typer.Option(
@@ -483,6 +494,7 @@ def serve(
     try:
         project_id = engine.serve(
             image_names,
+            host_ip,
             ports,
             volume,
             gpus,
@@ -538,7 +550,9 @@ def _display_tesseract_image_meta() -> None:
 
 def _display_tesseract_containers_meta() -> None:
     """Display Tesseract containers metadata."""
-    table = RichTable("ID", "Name", "Version", "Host Port", "Project ID", "Description")
+    table = RichTable(
+        "ID", "Name", "Version", "Host Address", "Project ID", "Description"
+    )
     containers = docker_client.containers.list()
     for container in containers:
         tesseract_vals = _get_tesseract_env_vals(container)
@@ -548,7 +562,7 @@ def _display_tesseract_containers_meta() -> None:
                 container.id[:12],
                 tesseract_vals["TESSERACT_NAME"],
                 tesseract_vals["TESSERACT_VERSION"],
-                container.host_port,
+                f"{container.host_ip}:{container.host_port}",
                 tesseract_project,
                 tesseract_vals.get("TESSERACT_DESCRIPTION", "").replace("\\n", " "),
             )
@@ -595,10 +609,11 @@ def apidoc(
     ] = True,
 ) -> None:
     """Serve the OpenAPI schema for a Tesseract."""
-    project_id = engine.serve([image_name], no_compose=True)
+    host_ip = "127.0.0.1"
+    project_id = engine.serve([image_name], no_compose=True, host_ip=host_ip)
     try:
         container = docker_client.containers.get(project_id)
-        url = f"http://localhost:{container.host_port}/docs"
+        url = f"http://{host_ip}:{container.host_port}/docs"
         logger.info(f"Serving OpenAPI docs for Tesseract {image_name} at {url}")
         logger.info("  Press Ctrl+C to stop")
         if browser:
@@ -632,8 +647,11 @@ def _display_project_meta(project_id: str) -> list:
         entrypoint = container.attrs["Config"]["Entrypoint"]
         logger.info(f"Entrypoint: {entrypoint}")
         host_port = container.host_port
-        logger.info(f"View Tesseract: http://localhost:{host_port}/docs")
-        container_ports.append({"name": container.name, "port": host_port})
+        host_ip = container.host_ip
+        logger.info(f"View Tesseract: http://{host_ip}:{host_port}/docs")
+        container_ports.append(
+            {"name": container.name, "port": host_port, "ip": host_ip}
+        )
 
     return container_ports
 

tesseract_core/sdk/docker_client.py

@@ -263,8 +263,9 @@ def _get_images(tesseract_only: bool = True) -> list_[Image]:
 class Container:
     """Container class to wrap Docker container details.
 
-    Container class has additional member variable `host_port` that docker-py
-    does not have. This is because Tesseract requires frequent access to the host port.
+    Container class has additional member variables `host_port` and `host_ip` that
+    docker-py does not have. This is because Tesseract requires frequent access to the host
+    port mappings.
     """
 
     id: str
@@ -301,6 +302,17 @@ def host_port(self) -> str | None:
                     return ports[port_key][0].get("HostPort")
         return None
 
+    @property
+    def host_ip(self) -> str | None:
+        """Gets the host IP of the container."""
+        if self.attrs.get("NetworkSettings", None):
+            ports = self.attrs["NetworkSettings"].get("Ports", None)
+            if ports:
+                port_key = next(iter(ports))  # Get the first port key
+                if ports[port_key]:
+                    return ports[port_key][0].get("HostIp")
+        return None
+
     @property
     def project_id(self) -> str | None:
         """Gets the project ID of the container."""

tesseract_core/sdk/engine.py

@@ -119,7 +119,7 @@ def wrapper_needs_docker(*args: Any, **kwargs: Any) -> None:
 
 
 def get_free_port(
-    within_range: tuple[int, int] | None = (49152, 65535),
+    within_range: tuple[int, int] = (49152, 65535),
     exclude: Sequence[int] = (),
 ) -> int:
     """Find a random free port to use for HTTP."""
@@ -136,7 +136,7 @@ def get_free_port(
         # Check if the port is free
         with closing(socket.socket(socket.AF_INET, socket.SOCK_STREAM)) as s:
             try:
-                s.bind(("localhost", port))
+                s.bind(("127.0.0.1", port))
             except OSError:
                 # Port is already in use
                 continue
@@ -537,6 +537,7 @@ def get_project_containers(project_id: str) -> list[Container]:
 
 def serve(
     images: list[str],
+    host_ip: str = "127.0.0.1",
     ports: list[str] | None = None,
     volumes: list[str] | None = None,
     gpus: list[str] | None = None,
@@ -550,6 +551,7 @@ def serve(
 
     Args:
         images: a list of Tesseract image IDs as strings.
+        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.
         gpus: IDs of host Nvidia GPUs to make available to the Tesseracts.
@@ -597,22 +599,30 @@ def serve(
         if propagate_tracebacks:
             args.append("--debug")
 
-        logger.info(f"Serving Tesseract at http://localhost:{port}")
-        logger.info(f"View Tesseract: http://localhost:{port}/docs")
+        # Always bind to all interfaces inside the container
+        args.extend(["--host", "0.0.0.0"])
+
+        if host_ip == "0.0.0.0":
+            ping_ip = "127.0.0.1"
+        else:
+            ping_ip = host_ip
+
+        logger.info(f"Serving Tesseract at http://{ping_ip}:{port}")
+        logger.info(f"View Tesseract: http://{ping_ip}:{port}/docs")
 
         container = docker_client.containers.run(
             image=image_ids[0],
             command=["serve", *args],
             device_requests=gpus,
-            ports={f"{port}": "8000"},
+            ports={f"{host_ip}:{port}": container_port},
             detach=True,
             volumes=volumes,
         )
         # wait for server to start
         timeout = 30
         while True:
             try:
-                response = requests.get(f"http://localhost:{port}/health")
+                response = requests.get(f"http://{ping_ip}:{port}/health")
             except requests.exceptions.ConnectionError:
                 pass
             else:
@@ -628,7 +638,13 @@ def serve(
         return container.name
 
     template = _create_docker_compose_template(
-        image_ids, ports, volumes, gpus, num_workers, debug=propagate_tracebacks
+        image_ids,
+        host_ip,
+        ports,
+        volumes,
+        gpus,
+        num_workers,
+        debug=propagate_tracebacks,
     )
     compose_fname = f"docker-compose-{_id_generator()}.yml"
 
@@ -647,6 +663,7 @@ def serve(
 
 def _create_docker_compose_template(
     image_ids: list[str],
+    host_ip: str = "127.0.0.1",
     ports: list[str] | None = None,
     volumes: list[str] | None = None,
     gpus: list[str] | None = None,
@@ -674,6 +691,9 @@ def _create_docker_compose_template(
                 )
             )
 
+    # Prepend host IP to ports
+    ports = [f"{host_ip}:{port}" for port in ports]
+
     gpu_settings = None
     if gpus:
         if (len(gpus) == 1) and (gpus[0] == "all"):
@@ -691,11 +711,12 @@ def _create_docker_compose_template(
             "environment": {
                 "TESSERACT_DEBUG": "1" if debug else "0",
             },
+            "num_workers": num_workers,
         }
 
         services.append(service)
     template = ENV.get_template("docker-compose.yml")
-    return template.render(services=services, num_workers=num_workers)
+    return template.render(services=services)
 
 
 def _id_generator(

tesseract_core/sdk/templates/docker-compose.yml

@@ -3,7 +3,7 @@ services:
   {{ service.name }}:
     image: {{ service.image }}
     restart: unless-stopped
-    command: ["serve", "--num-workers", "{{ num_workers }}"]
+    command: ["serve", "--host", "0.0.0.0", "--num-workers", "{{ service.num_workers }}"]
     ports:
       - {{ service.port }}
     {%- if service.volumes %}

tesseract_core/sdk/tesseract.py

@@ -204,11 +204,12 @@ def server_logs(self) -> str:
             return self._lastlog
         return engine.logs(self._serve_context["container_id"])
 
-    def serve(self, port: str | None = None) -> None:
+    def serve(self, port: str | None = None, host_ip: str = "127.0.0.1") -> None:
         """Serve the Tesseract.
 
         Args:
             port: Port to serve the Tesseract on.
+            host_ip: IP address of the host to bind the Tesseract to.
         """
         if self._spawn_config is None:
             raise RuntimeError("Can only serve a Tesseract created via from_image.")
@@ -221,14 +222,15 @@ def serve(self, port: str | None = None) -> None:
             gpus=self._spawn_config.gpus,
             num_workers=self._spawn_config.num_workers,
             debug=self._spawn_config.debug,
+            host_ip=host_ip,
         )
         self._serve_context = dict(
             project_id=project_id,
             container_id=container_id,
             port=served_port,
         )
         self._lastlog = None
-        self._client = HTTPClient(f"http://localhost:{served_port}")
+        self._client = HTTPClient(f"http://{host_ip}:{served_port}")
         atexit.register(self.teardown)
 
     def teardown(self) -> None:
@@ -256,6 +258,7 @@ def __del__(self) -> None:
     def _serve(
         image: str,
         port: str | None = None,
+        host_ip: str = "127.0.0.1",
         volumes: list[str] | None = None,
         gpus: list[str] | None = None,
         debug: bool = False,
@@ -273,6 +276,7 @@ def _serve(
             gpus=gpus,
             propagate_tracebacks=debug,
             num_workers=num_workers,
+            host_ip=host_ip,
         )
 
         first_container = engine.get_project_containers(project_id)[0]

tests/conftest.py

@@ -196,7 +196,7 @@ def free_port():
     from contextlib import closing
 
     with closing(socket.socket(socket.AF_INET, socket.SOCK_STREAM)) as s:
-        s.bind(("localhost", 0))
+        s.bind(("127.0.0.1", 0))
         return s.getsockname()[1]
 
 
@@ -246,7 +246,7 @@ def cleanup_func():
         for container in context["containers"]:
             try:
                 if isinstance(container, str):
-                    container_obj = docker_client.containers.get(container.id)
+                    container_obj = docker_client.containers.get(container)
                 else:
                     container_obj = container