Launch docker image from PyGeometry (#337)

RobPasMue · web-flow · commit 89215f2ad195 · 2023-01-25T14:03:34.000Z
diff --git a/.github/workflows/ci_cd.yml b/.github/workflows/ci_cd.yml
@@ -13,7 +13,7 @@ env:
   PACKAGE_NAME: 'ansys-geometry-core'
   PACKAGE_NAMESPACE: 'ansys.geometry.core'
   DOCUMENTATION_CNAME: 'geometry.docs.pyansys.com'
-  ANSRV_GEO_IMAGE: ghcr.io/pyansys/pygeometry:latest
+  ANSRV_GEO_IMAGE: ghcr.io/pyansys/pygeometry:windows-latest
   ANSRV_GEO_PORT: 700
   GEO_CONT_NAME: ans_geo
   RESET_IMAGE_CACHE: 6
diff --git a/.github/workflows/nightly_docker_test.yml b/.github/workflows/nightly_docker_test.yml
@@ -17,7 +17,7 @@ jobs:
     name: Run all tests against server
     runs-on: [self-hosted, pygeometry]
     env:
-      ANSRV_GEO_IMAGE: ghcr.io/pyansys/pygeometry:latest-unstable
+      ANSRV_GEO_IMAGE: ghcr.io/pyansys/pygeometry:windows-latest-unstable
       ANSRV_GEO_PORT: 710
       GEO_CONT_NAME: ans_geo_nightly
 
diff --git a/README.rst b/README.rst
@@ -36,14 +36,56 @@ PyGeometry is a Python client library for the Ansys Geometry service.
 Usage
 -----
 
+There are two different ways of getting started with the Geometry Service and its client-library, PyGeometry.
+
+Using PyGeometry launcher
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+PyGeometry is provided with an internal launcher that is capable of handling the specifics of
+launching the Geometry Service locally. The only requirements are that:
+
+* Docker is installed on your machine.
+* You have access to the PyAnsys GitHub container registry, where the Geometry Service image is hosted.
+
+.. caution::
+
+   The Geometry Service is currently available only as a Windows Docker image. The development
+   team is working on getting the Linux Docker container available as soon as possible. In the meantime,
+   make sure that your Docker engine is configured to run Windows Docker images.
+
+First, bear in mind that you have to be `authenticated to ghcr.io
+<https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry>`_.
+Once authenticated, please proceed to download the Geometry Service Docker image:
+
+.. code:: bash
+
+   docker pull ghcr.io/pyansys/pygeometry:<tag>
+
+The following OS-dependent tags are available:
+
+* ``windows-latest``
+* ``windows-latest-unstable``
+
+Next, you will be ready to run the Geometry Service directly from PyGeometry:
+
+.. code:: python
+
+   from ansys.geometry.core.connection import launch_modeler
+
+   modeler = launch_modeler()
+
+The previous ``launch_modeler()`` method will launch the Geometry Service under the default
+conditions. For more configurability, please use ``launch_local_modeler()``.
+
+Manual service launch
+^^^^^^^^^^^^^^^^^^^^^
+
 First, start the Geometry service locally. If you have Docker installed and have
-`authenticated to ghcr.io
-<https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry>`_,
-you can start the service locally using Docker with:
+`authenticated to ghcr.io`_, you can start the service locally using Docker with:
 
 .. code:: bash
 
-   docker run --name ans_geo -p 50051:50051 ghcr.io/pyansys/pygeometry:latest
+   docker run --name ans_geo -p 50051:50051 ghcr.io/pyansys/pygeometry:windows-latest
 
 Next, connect to the service with:
 
diff --git a/doc/source/getting_started/docker.rst b/doc/source/getting_started/docker.rst
@@ -22,11 +22,47 @@ Install the PyGeometry image
       GH_USERNAME=<my-github-username>
       cat GH_TOKEN.txt | docker login docker.pkg.github.com -u $GH_USERNAME --password-stdin
 
-#. Launch the Geometry service locally using Docker with:
+#. Pull the Geometry service locally using Docker with:
+
 
    .. code:: bash
 
-      docker run --name ans_geo -p 50051:50051 ghcr.io/pyansys/pygeometry:latest
+      docker pull ghcr.io/pyansys/pygeometry:<tag>
+
+   The following OS-dependent tags are available:
+
+   * ``windows-latest``
+   * ``windows-latest-unstable``
+
+Launching the Geometry service
+------------------------------
+
+The Geometry service can be launched locally in two different ways:
+
+.. tab-set:: 
+
+    .. tab-item:: Using PyGeometry launcher
+
+        This method will directly launch for you the Geometry Service and it
+        will provide a ``Modeler`` object.
+
+        .. code:: python
+
+          from ansys.geometry.core.connection import launch_modeler
+
+          modeler = launch_modeler()
+
+        The previous ``launch_modeler()`` method will launch the Geometry Service under the default
+        conditions. For more configurability, please use ``launch_local_modeler()``.
+
+    .. tab-item:: Manual Geometry Service launch
+
+       This method will involve the user manually launching the Geometry Service. Afterwards, please
+       refer to the next section in order to understand how to connect to it from PyGeometry.
+
+       .. code:: bash
+
+          docker run --name ans_geo -p 50051:50051 ghcr.io/pyansys/pygeometry:windows-latest
 
 
 Connect to the Geometry service
diff --git a/doc/source/user_guide/shapes.rst b/doc/source/user_guide/shapes.rst
@@ -42,6 +42,7 @@ which take as a starting point the last point of the previous edge.
 It is also able to get a desired shape of the sketch object by taking advantage of the user-defined labels.
 
 .. code:: python
+
     sketch.get("<tag>")
 
 .. jupyter-execute::
diff --git a/pyproject.toml b/pyproject.toml
@@ -38,6 +38,7 @@ dependencies = [
     "pyvista>=0.37.0",
     "scipy>=1.7.3",
     "six>=1.16.0",
+    "docker>=6.0.1",
 ]
 
 [project.optional-dependencies]
diff --git a/src/ansys/geometry/core/__init__.py b/src/ansys/geometry/core/__init__.py
@@ -15,6 +15,10 @@
 # Ease import statements
 # ------------------------------------------------------------------------------
 
-from ansys.geometry.core.connection.launcher import launch_modeler
+from ansys.geometry.core.connection.launcher import (
+    launch_local_modeler,
+    launch_modeler,
+    launch_remote_modeler,
+)
 from ansys.geometry.core.logger import LOG
 from ansys.geometry.core.modeler import Modeler
diff --git a/src/ansys/geometry/core/connection/__init__.py b/src/ansys/geometry/core/connection/__init__.py
@@ -8,4 +8,9 @@
     unit_vector_to_grpc_direction,
 )
 from ansys.geometry.core.connection.defaults import DEFAULT_HOST, DEFAULT_PORT
-from ansys.geometry.core.connection.launcher import launch_modeler
+from ansys.geometry.core.connection.launcher import (
+    launch_local_modeler,
+    launch_modeler,
+    launch_remote_modeler,
+)
+from ansys.geometry.core.connection.localinstance import LocalDockerInstance
diff --git a/src/ansys/geometry/core/connection/client.py b/src/ansys/geometry/core/connection/client.py
@@ -11,6 +11,7 @@
 from grpc_health.v1 import health_pb2, health_pb2_grpc
 
 from ansys.geometry.core.connection.defaults import DEFAULT_HOST, DEFAULT_PORT, MAX_MESSAGE_LENGTH
+from ansys.geometry.core.connection.localinstance import LocalDockerInstance
 from ansys.geometry.core.logger import LOG as logger
 from ansys.geometry.core.logger import PyGeometryCustomAdapter
 from ansys.geometry.core.typing import Real
@@ -73,6 +74,11 @@ class GrpcClient:
         is launched through PyPIM. This instance is deleted when calling the
         :func:`GrpcClient.close <ansys.geometry.core.client.GrpcClient.close >`
         method.
+    local_instance : LocalDockerInstance, default: None
+        Corresponding local instance when the Geometry service is launched through
+        the ``launch_local_modeler()`` interface. This instance will be deleted
+        when the :func:`GrpcClient.close <ansys.geometry.core.client.GrpcClient.close >`
+        method is called.
     timeout : real, default: 60
         Timeout in seconds to achieve the connection.
     logging_level : int, default: INFO
@@ -88,13 +94,15 @@ def __init__(
         port: Union[str, int] = DEFAULT_PORT,
         channel: Optional[grpc.Channel] = None,
         remote_instance: Optional["Instance"] = None,
+        local_instance: Optional[LocalDockerInstance] = None,
         timeout: Optional[Real] = 60,
         logging_level: Optional[int] = logging.INFO,
         logging_file: Optional[Union[Path, str]] = None,
     ):
         """Initialize the ``GrpcClient`` object."""
         self._closed = False
         self._remote_instance = remote_instance
+        self._local_instance = local_instance
         if channel:
             # Used for PyPIM when directly providing a channel
             self._channel = channel
@@ -162,10 +170,18 @@ def close(self):
         Notes
         -----
         If an instance of the Geometry service was started using
-        PyPIM, this instance is deleted.
+        PyPIM, this instance is deleted. Furthermore, if a local instance
+        of the Geometry Service was started, it will be stopped.
         """
         if self._remote_instance:
             self._remote_instance.delete()  # pragma: no cover
+        if self._local_instance:
+            if not self._local_instance.existed_previously:
+                self._local_instance.container.stop()
+            else:
+                self.log.warning(
+                    "Geometry Service will not be shutdown since it was already running..."
+                )
         self._closed = True
         self._channel.close()
 
diff --git a/src/ansys/geometry/core/connection/defaults.py b/src/ansys/geometry/core/connection/defaults.py
@@ -10,7 +10,7 @@
 and if it does not exist, it falls back to ``127.0.0.1``.
 """
 
-DEFAULT_PORT = os.environ.get("ANSRV_GEO_PORT", 50051)
+DEFAULT_PORT: int = int(os.environ.get("ANSRV_GEO_PORT", 50051))
 """
 Default HOST port used.
 
@@ -25,3 +25,10 @@
 By default, it searches for the environment variable ``PYGEOMETRY_MAX_MESSAGE_LENGTH``,
 and if it does not exist, it falls back to ``256Mb``.
 """
+
+GEOMETRY_SERVICE_DOCKER_IMAGE = "ghcr.io/pyansys/pygeometry"
+"""
+Default Geometry Service Docker image location.
+
+Tag is dependent on what OS service is requested.
+"""
diff --git a/src/ansys/geometry/core/connection/launcher.py b/src/ansys/geometry/core/connection/launcher.py
@@ -1,6 +1,8 @@
 """Provides for connecting to Geometry service instances."""
 from beartype.typing import TYPE_CHECKING, Optional
 
+from ansys.geometry.core.connection.defaults import DEFAULT_PORT
+from ansys.geometry.core.connection.localinstance import GeometryContainers, LocalDockerInstance
 from ansys.geometry.core.logger import LOG as logger
 from ansys.geometry.core.misc import check_type
 
@@ -32,7 +34,7 @@ def launch_modeler() -> "Modeler":
     >>> from ansys.geometry.core import launch_modeler
     >>> modeler = launch_modeler()
     """
-    # A local installation of the Geometry service or PyPIM is required for
+    # A local Docker container of the Geometry service or PyPIM is required for
     # this to work. Neither is integrated, but we can consider adding them later.
 
     # Another alternative is to run Docker locally from this method.
@@ -43,7 +45,13 @@ def launch_modeler() -> "Modeler":
         logger.info("Starting Geometry service remotely. The startup configuration is ignored.")
         return launch_remote_modeler()
 
-    raise NotImplementedError("Not yet implemented.")
+    # Otherwise, we are in the "local Docker Container" scenario
+    if LocalDockerInstance.is_docker_installed():
+        logger.info("Starting Geometry service locally from Docker container.")
+        return launch_local_modeler()
+
+    # If we reached this point...
+    raise NotImplementedError("Geometry service cannot be initialized.")
 
 
 def launch_remote_modeler(
@@ -88,3 +96,60 @@ def launch_remote_modeler(
         ]
     )
     return Modeler(channel=channel, remote_instance=instance)
+
+
+def launch_local_modeler(
+    port: int = DEFAULT_PORT,
+    connect_to_existing_service: bool = True,
+    restart_if_existing_service: bool = False,
+    name: Optional[str] = None,
+    image: Optional[GeometryContainers] = None,
+) -> "Modeler":
+    """
+    Start the Geometry service locally using the ``LocalDockerInstance`` class.
+
+    When calling this method, a Geometry service (as a local Docker container)
+    is started. By default, if a container with the Geometry service already exists
+    at the given port, it will connect to it. Otherwise, it will try to launch its own
+    service.
+
+    Parameters
+    ----------
+    port : int, optional
+        Localhost port at which the Geometry Service will be deployed or which
+        the ``Modeler`` will connect to (if it is already deployed). By default,
+        value will be the one at ``DEFAULT_PORT``.
+    connect_to_existing_service : bool, optional
+        Boolean indicating whether if the Modeler should connect to a Geometry
+        Service already deployed at that port, by default ``True``.
+    restart_if_existing_service : bool, optional
+        Boolean indicating whether the Geometry Service (which is already running)
+        should be restarted when attempting connection, by default ``False``
+    name : Optional[str], optional
+        Name of the Docker container to be deployed, by default ``None``, which
+        means that Docker will assign it a random name.
+    image : Optional[GeometryContainers], optional
+        The Geometry Service Docker image to be deployed, by default ``None``, which
+        means that the ``LocalDockerInstance`` class will identify the OS of your
+        Docker engine and deploy the latest version of the Geometry Service for that
+        OS.
+
+    Returns
+    -------
+    Modeler
+        Instance of the Geometry service.
+    """
+
+    from ansys.geometry.core.modeler import Modeler
+
+    # Call the LocalDockerInstance ctor.
+    local_instance = LocalDockerInstance(
+        port=port,
+        connect_to_existing_service=connect_to_existing_service,
+        restart_if_existing_service=restart_if_existing_service,
+        name=name,
+        image=image,
+    )
+
+    # Once the local instance is ready... return the Modeler
+    return Modeler(host="localhost", port=port, local_instance=local_instance)
diff --git a/src/ansys/geometry/core/connection/localinstance.py b/src/ansys/geometry/core/connection/localinstance.py
diff --git a/src/ansys/geometry/core/modeler.py b/src/ansys/geometry/core/modeler.py
diff --git a/tests/integration/test_launcher_local.py b/tests/integration/test_launcher_local.py
diff --git a/tests/integration/test_launcher_remote.py b/tests/integration/test_launcher_remote.py

Original file line number	Diff line number	Diff line change
`@@ -38,6 +38,7 @@ dependencies = [`
`38`	`38`	`"pyvista>=0.37.0",`
`39`	`39`	`"scipy>=1.7.3",`
`40`	`40`	`"six>=1.16.0",`
	`41`	`+ "docker>=6.0.1",`
`41`	`42`	`]`
`42`	`43`
`43`	`44`	`[project.optional-dependencies]`