Implementation of API server on Geometry Service (#291)

Co-authored-by: Roberto Pastor Muela <[email protected]>
Co-authored-by: Maxime Rey <[email protected]>

Author: 3 people

.ci/clean_registry.py

@@ -0,0 +1,41 @@
+import os
+
+from ghapi.all import GhApi
+from ghapi.core import print_summary
+from ghapi.page import paged
+
+org_str = "pyansys"
+pck_str = "geometry"
+valid_tags = ["windows-latest", "windows-latest-unstable", "linux-latest", "linux-latest-unstable"]
+
+api = GhApi(debug=print_summary, token=os.getenv("PACKAGE_DELETION_TOKEN"))
+
+paged_packages = paged(
+    api.packages.get_all_package_versions_for_package_owned_by_org,
+    org=org_str,
+    package_name=pck_str,
+    package_type="container",
+    state="active",
+    per_page=100,
+)
+
+# Loop over all pages
+for page in paged_packages:
+    for package in page:
+        # Check if the given package should be deleted
+        package_tags = package.metadata.container.tags
+        delete = True
+        for tag in package_tags:
+            if tag in valid_tags:
+                delete = False
+                break
+
+        # In case it should, delete it
+        if delete:
+            print("Deleting:" + package)
+            api.packages.delete_package_version_for_org(
+                org=org_str,
+                package_name=pck_str,
+                package_type="container",
+                package_version_id=package["id"],
+            )

.github/workflows/ci_cd.yml

@@ -13,8 +13,9 @@ env:
   PACKAGE_NAME: 'ansys-geometry-core'
   PACKAGE_NAMESPACE: 'ansys.geometry.core'
   DOCUMENTATION_CNAME: 'geometry.docs.pyansys.com'
-  ANSRV_GEO_IMAGE: ghcr.io/pyansys/pygeometry:windows-latest
+  ANSRV_GEO_IMAGE: ghcr.io/pyansys/geometry:windows-latest
   ANSRV_GEO_PORT: 700
+  ANSRV_GEO_LICENSE_SERVER: ${{ secrets.LICENSE_SERVER }}
   GEO_CONT_NAME: ans_geo
   RESET_IMAGE_CACHE: 6
   IS_WORKFLOW_RUNNING: True
@@ -127,7 +128,7 @@ jobs:
         run: |
           .\.venv\Scripts\Activate.ps1
           $env:ANSRV_GEO_PORT_MAP = $env:ANSRV_GEO_PORT + ":50051"
-          docker run --detach --name $env:GEO_CONT_NAME -p $env:ANSRV_GEO_PORT_MAP $env:ANSRV_GEO_IMAGE
+          docker run --detach --name $env:GEO_CONT_NAME -e LICENSE_SERVER=$env:ANSRV_GEO_LICENSE_SERVER -p $env:ANSRV_GEO_PORT_MAP $env:ANSRV_GEO_IMAGE
           python -c "from ansys.geometry.core.connection.validate import validate; validate()"
       
       - uses: actions/cache@v3
@@ -215,7 +216,7 @@ jobs:
         run: |
           .\.venv\Scripts\Activate.ps1
           $env:ANSRV_GEO_PORT_MAP = $env:ANSRV_GEO_PORT + ":50051"
-          docker run --detach --name $env:GEO_CONT_NAME -p $env:ANSRV_GEO_PORT_MAP $env:ANSRV_GEO_IMAGE
+          docker run --detach --name $env:GEO_CONT_NAME -e LICENSE_SERVER=$env:ANSRV_GEO_LICENSE_SERVER -p $env:ANSRV_GEO_PORT_MAP $env:ANSRV_GEO_IMAGE
           python -c "from ansys.geometry.core.connection.validate import validate; validate()"
 
       - name: Build the documentation (HTML)

.github/workflows/nightly_docker_test.yml

@@ -17,8 +17,9 @@ jobs:
     name: Run all tests against server
     runs-on: [self-hosted, pygeometry]
     env:
-      ANSRV_GEO_IMAGE: ghcr.io/pyansys/pygeometry:windows-latest-unstable
+      ANSRV_GEO_IMAGE: ghcr.io/pyansys/geometry:windows-latest-unstable
       ANSRV_GEO_PORT: 710
+      ANSRV_GEO_LICENSE_SERVER: ${{ secrets.LICENSE_SERVER }}
       GEO_CONT_NAME: ans_geo_nightly
 
     steps:
@@ -59,7 +60,7 @@ jobs:
         run: |
           .\.venv\Scripts\Activate.ps1
           $env:ANSRV_GEO_PORT_MAP = $env:ANSRV_GEO_PORT + ":50051"
-          docker run --detach --name $env:GEO_CONT_NAME -p $env:ANSRV_GEO_PORT_MAP $env:ANSRV_GEO_IMAGE
+          docker run --detach --name $env:GEO_CONT_NAME -e LICENSE_SERVER=$env:ANSRV_GEO_LICENSE_SERVER -p $env:ANSRV_GEO_PORT_MAP $env:ANSRV_GEO_IMAGE
           python -c "from ansys.geometry.core.connection.validate import validate; validate()"
 
       - name: Run PyGeometry tests

.github/workflows/package_cleanup.yml

@@ -0,0 +1,35 @@
+name: Geometry Service - Package cleanup
+on:
+  workflow_dispatch:
+  schedule: # UTC at 0200
+    - cron: "0 2 * * *"
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: write
+  packages: write
+
+jobs:
+  cleanup:
+    name: Cleaning unnecessary packages
+    runs-on: ubuntu-latest
+    env:
+      PACKAGE_DELETION_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+    steps:
+      - name: "Checkout repository"
+        uses: actions/checkout@v3
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+
+      - name: "Install requirements"
+        run: |
+          pip install ghapi
+
+      - name: "Perform cleanup"
+        run: |
+          python -m .ci/clean_registry.py

README.rst

@@ -36,45 +36,45 @@ 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.
+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:
+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.
+* 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
+   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:
+Once authenticated, please proceed to download the Geometry service Docker image:
 
 .. code:: bash
 
-   docker pull ghcr.io/pyansys/pygeometry:<tag>
+   docker pull ghcr.io/pyansys/geometry:<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:
+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
+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
@@ -85,7 +85,17 @@ First, start the Geometry service locally. If you have Docker installed and have
 
 .. code:: bash
 
-   docker run --name ans_geo -p 50051:50051 ghcr.io/pyansys/pygeometry:windows-latest
+   docker run --name ans_geo -e LICENSE_SERVER=<LICENSE-SERVER> -p 50051:50051 ghcr.io/pyansys/geometry:windows-latest
+
+The Geometry service has a set of environment variables that are **mandatory**:
+
+* ``LICENSE_SERVER``: the license server (IP, DNS) to which the Geometry service shall connect. For example, ``127.0.0.1``.
+
+Other optional environment variables are:
+
+* ``ENABLE_TRACE``: whether to set up the trace level for debugging purposes. Expects either ``1`` or ``0``.
+  By default, ``0`` (which means it is not activated).
+* ``LOG_LEVEL``: sets the Geometry service logging level. By default, ``2``.
 
 Next, connect to the service with:
 

doc/source/getting_started/docker.rst

@@ -27,7 +27,7 @@ Install the PyGeometry image
 
    .. code:: bash
 
-      docker pull ghcr.io/pyansys/pygeometry:<tag>
+      docker pull ghcr.io/pyansys/geometry:<tag>
 
    The following OS-dependent tags are available:
 
@@ -37,13 +37,65 @@ Install the PyGeometry image
 Launching the Geometry service
 ------------------------------
 
+In this section there are two mechanisms for launching the Geometry service: either **using the PyGeometry launcher**
+or **manually launching the service**.
+
+Environment variables
+^^^^^^^^^^^^^^^^^^^^^
+
+The Geometry service has a set of environment variables that are **mandatory** for its use:
+
+* ``LICENSE_SERVER``: the license server (IP, DNS) to which the Geometry service shall connect. For example, ``127.0.0.1``.
+
+Other optional environment variables are:
+
+* ``ENABLE_TRACE``: whether to set up the trace level for debugging purposes. Expects either ``1`` or ``0``.
+  By default, ``0`` (which means it is not activated).
+* ``LOG_LEVEL``: sets the Geometry service logging level. By default, ``2``.
+
+Depending on the mechanism chosen to launch the Geometry service, you can set them as follows:
+
+.. tab-set:: 
+
+    .. tab-item:: Using PyGeometry launcher
+
+        In this case, users will have to define the following general environment variables prior
+        to launching it. Bare in mind that the naming of the variables is not the same:
+
+        .. tab-set::
+
+            .. tab-item:: Linux/Mac
+
+                .. code-block:: bash
+
+                    export ANSRV_GEO_LICENSE_SERVER=127.0.0.1
+                    export ANSRV_GEO_ENABLE_TRACE=0
+                    export ANSRV_GEO_LOG_LEVEL=2
+
+            .. tab-item:: Windows
+
+                .. code-block:: bash
+
+                    SET ANSRV_GEO_LICENSE_SERVER=127.0.0.1
+                    SET ANSRV_GEO_ENABLE_TRACE=0
+                    SET ANSRV_GEO_LOG_LEVEL=2
+
+    .. tab-item:: Manual Geometry service launch
+
+        In this case, there is no prior environment variable definition needed. They can
+        directly be passed to the Docker container itself.
+
+
+Geometry service launcher
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
 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
+        This method will directly launch for you the Geometry service and it
         will provide a ``Modeler`` object.
 
         .. code:: python
@@ -52,17 +104,18 @@ The Geometry service can be launched locally in two different ways:
 
           modeler = launch_modeler()
 
-        The previous ``launch_modeler()`` method will launch the Geometry Service under the default
+        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
+    .. 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.
+       This method will involve the user manually launching the Geometry service. Remember to pass
+       in the different environment variables needed. 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
+          docker run --name ans_geo -e LICENSE_SERVER=<LICENSE_SERVER> -p 50051:50051 ghcr.io/pyansys/geometry:windows-latest
 
 
 Connect to the Geometry service

pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "flit_core.buildapi"
 [project]
 name = "ansys-geometry-core"
 version = "0.2.dev0"
-description = "A python wrapper for Ansys Geometry Service"
+description = "A python wrapper for Ansys Geometry service"
 readme = "README.rst"
 requires-python = ">=3.7,<4"
 license = {file = "LICENSE"}
@@ -25,7 +25,7 @@ classifiers = [
 ]
 
 dependencies = [
-    "ansys-api-geometry==0.1.3",
+    "ansys-api-geometry==0.2.0",
     "beartype>=0.11.0",
     "google-api-python-client>=1.7.11",
     "googleapis-common-protos>=1.52.0",
@@ -38,7 +38,6 @@ dependencies = [
     "pyvista>=0.37.0",
     "scipy>=1.7.3",
     "six>=1.16.0",
-    "docker>=6.0.1",
 ]
 
 [project.optional-dependencies]
@@ -55,6 +54,7 @@ tests = [
     "scipy==1.10.0",
     "six==1.16.0",
     "ansys-platform-instancemanagement==1.0.3",
+    "docker==6.0.1",
     "pytest==7.2.1",
     "pytest-cov==4.0.0",
     "pytest-pyvista==0.1.5",
@@ -70,9 +70,9 @@ doc = [
     "notebook==6.5.2",
     "numpydoc==1.5.0",
     "panel==0.14.3",
-    "Sphinx==5.1.1",
+    "Sphinx==5.1.1",                        # PR349 - Duplicated documentation entries...
     "sphinx-autoapi==2.0.1",
-    "sphinx-autodoc-typehints==1.19.1",
+    "sphinx-autodoc-typehints==1.19.1",     # PR349 - Duplicated documentation entries...
     "sphinx-copybutton==0.5.1",
     "sphinx_design==0.3.0",
     "sphinx-gallery==0.7.0",

src/ansys/geometry/core/connection/client.py

@@ -176,7 +176,7 @@ def close(self):
         -----
         If an instance of the Geometry service was started using
         PyPIM, this instance is deleted. Furthermore, if a local instance
-        of the Geometry Service was started, it will be stopped.
+        of the Geometry service was started, it will be stopped.
         """
         if self._remote_instance:
             self._remote_instance.delete()  # pragma: no cover
@@ -185,7 +185,7 @@ def close(self):
                 self._local_instance.container.stop()
             else:
                 self.log.warning(
-                    "Geometry Service will not be shutdown since it was already running..."
+                    "Geometry service will not be shutdown since it was already running..."
                 )
         self._closed = True
         self._channel.close()

src/ansys/geometry/core/connection/defaults.py

@@ -26,9 +26,9 @@
 and if it does not exist, it falls back to ``256Mb``.
 """
 
-GEOMETRY_SERVICE_DOCKER_IMAGE = "ghcr.io/pyansys/pygeometry"
+GEOMETRY_SERVICE_DOCKER_IMAGE = "ghcr.io/pyansys/geometry"
 """
-Default Geometry Service Docker image location.
+Default Geometry service Docker image location.
 
 Tag is dependent on what OS service is requested.
 """