Windows Docker container

Docker for Windows containers

To run the Windows Docker container for the Geometry service, ensure that you follow these steps when installing Docker:

1. Install Docker Desktop.

2. When prompted for Use WSL2 instead of Hyper-V (recommended), clear this checkbox. Hyper-V must be enabled to run Windows Docker containers.

3. Once the installation finishes, restart your machine and start Docker Desktop.

4. On the Windows taskbar, go to the Show hidden icons section, right-click in the Docker Desktop app, and select Switch to Windows containers.

Now that your Docker engine supports running Windows Docker containers, you can build or install the PyAnsys Geometry image.

Build or install the Geometry service image

There are two options for installing the PyAnsys Geometry image:

• Download it from the GitHub Container Registry.

• Build the Geometry service Windows container.

GitHub Container Registry

Note

This option is only available for users with write access to the repository or who are members of the Ansys organization.

Once Docker is installed on your machine, follow these steps to download the Windows Docker container for the Geometry service and install this image.

1. Using your GitHub credentials, download the Docker image from the PyAnsys Geometry repository on GitHub.

2. Use a GitHub personal access token with permission for reading packages to authorize Docker to access this repository. For more information, see Managing your personal access tokens in the GitHub documentation.

3. Save the token to a file with this command:

   echo XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX > GH_TOKEN.txt
   

4. Authorize Docker to access the repository and run the commands for your OS. To see these commands, click the tab for your OS.

   Powershell

   $env:GH_USERNAME=<my-github-username>
   cat GH_TOKEN.txt | docker login ghcr.io -u $env:GH_USERNAME --password-stdin
   

   Windows CMD

   SET GH_USERNAME=<my-github-username>
   type GH_TOKEN.txt | docker login ghcr.io -u %GH_USERNAME% --password-stdin
   

5. Pull the Geometry service locally using Docker with a command like this:

   docker pull ghcr.io/ansys/geometry:windows-latest
   

Build the Geometry service Windows container

The Geometry service Docker containers can be easily built by following these steps.

Inside the repository’s docker folder, there are two Dockerfile files:

• linux/Dockerfile: Builds the Linux-based Docker image.

• windows/Dockerfile: Builds the Windows-based Docker image.

Depending on the characteristics of the Docker engine installed on your machine, either one or the other has to be built.

This guide focuses on building the windows/Dockerfile image.

There are two build modes:

• Build from available Ansys installation: This mode builds the Docker image using the Ansys installation available in the machine where the Docker image is being built.

• Build from available binaries: This mode builds the Docker image using the binaries available in the ansys/pyansys-geometry-binaries repository. If you do not have access to this repository, you can only use the first mode.

Prerequisites

• Ensure that Docker is installed in your machine. If you do not have Docker available, see Docker for Windows containers.

Build from available Ansys installation

To build your own image based on your own Ansys installation, follow these instructions:

• Download the Python Docker build script.

• Execute the script with the following command (no specific location needed):

  python build_docker_windows.py
  

Check that the image has been created successfully. You should see output similar to this:

docker images

>>> REPOSITORY                                               TAG                                IMAGE ID       CREATED          SIZE
>>> ghcr.io/ansys/geometry                                   windows-******                     ............   X seconds ago    Y.ZZGB
>>> ......                                                   ......                             ............   ..............   ......

Build the Docker image from available binaries

Prior to building your image, follow these steps:

• Download the latest Windows Dockerfile.

• Download the latest release artifacts for the Windows Docker container (ZIP file) for your version.

Note

Only users with access to ansys/pyansys-geometry-binaries can download these binaries.

• Move this ZIP file to the location of the Windows Dockerfile previously downloaded.

To build your image, follow these instructions:

1. Navigate to the folder where the ZIP file and Dockerfile are located.

2. Run this Docker command:

   docker build -t ghcr.io/ansys/geometry:windows-latest -f windows/Dockerfile .
   

3. Check that the image has been created successfully. You should see output similar to this:

   docker images
   
   >>> REPOSITORY                                               TAG                                IMAGE ID       CREATED          SIZE
   >>> ghcr.io/ansys/geometry                                   windows-******                     ............   X seconds ago    Y.ZZGB
   >>> ......                                                   ......                             ............   ..............   ......
   

Launch the Geometry service

There are methods for launching the Geometry service:

• You can use the PyAnsys Geometry launcher.

• You can manually launch the Geometry service.

Environment variables

The Geometry service requires this mandatory environment variable for its use:

• LICENSE_SERVER: License server (IP address or DNS) that the Geometry service is to connect to. For example, 127.0.0.1.

You can also specify other optional environment variables:

• ENABLE_TRACE: Whether to set up the trace level for debugging purposes. The default is 0, in which case the trace level is not set up. Options are 1 and 0.

• LOG_LEVEL: Sets the Geometry service logging level. The default is 2, in which case the logging level is INFO.

Here are some terms to keep in mind:

• host: Machine that hosts the Geometry service. It is typically on localhost, but if you are deploying the service on a remote machine, you must pass in this host machine’s IP address when connecting. By default, PyAnsys Geometry assumes it is on localhost.

• port: Port that exposes the Geometry service on the host machine. Its value is assumed to be 50051, but users can deploy the service on preferred ports.

Prior to using the PyAnsys Geometry launcher to launch the Geometry service, you must define general environment variables required for your OS. You do not need to define these environment variables prior to manually launching the Geometry service.

Using PyAnsys Geometry launcher

Define the following general environment variables prior to using the PyAnsys Geometry launcher. Click the tab for your OS to see the appropriate commands.

Linux/Mac

export ANSRV_GEO_LICENSE_SERVER=127.0.0.1
export ANSRV_GEO_ENABLE_TRACE=0
export ANSRV_GEO_LOG_LEVEL=2
export ANSRV_GEO_HOST=127.0.0.1
export ANSRV_GEO_PORT=50051

Powershell

$env:ANSRV_GEO_LICENSE_SERVER="127.0.0.1"
$env:ANSRV_GEO_ENABLE_TRACE=0
$env:ANSRV_GEO_LOG_LEVEL=2
$env:ANSRV_GEO_HOST="127.0.0.1"
$env:ANSRV_GEO_PORT=50051

Windows CMD

SET ANSRV_GEO_LICENSE_SERVER=127.0.0.1
SET ANSRV_GEO_ENABLE_TRACE=0
SET ANSRV_GEO_LOG_LEVEL=2
SET ANSRV_GEO_HOST=127.0.0.1
SET ANSRV_GEO_PORT=50051

Warning

When running a Windows Docker container, certain high-value ports might be restricted from its use. This means that the port exposed by the container has to be set to lower values. You should change the value of ANSRV_GEO_PORT to use a port such as 700, instead of 50051.

Manual launch

You do not need to define general environment variables prior to manually launching the Geometry service. They are directly passed to the Docker container itself.

Geometry service launcher

As mentioned earlier, you can launch the Geometry service locally in two different ways. To see the commands for each method, click the following tabs.

Using PyAnsys Geometry launcher

This method directly launches the Geometry service and provides a Modeler object.

from ansys.geometry.core.connection import launch_modeler

modeler = launch_modeler()

The launch_modeler() method launches the Geometry service under the default conditions. For more configurability, use the launch_docker_modeler() method.

Manual launch

This method requires that you manually launch the Geometry service. Remember to pass in the different environment variables that are needed. Afterwards, see the next section to understand how to connect to this service instance from PyAnsys Geometry.

Linux/Mac

docker run \
    --name ans_geo \
    -e LICENSE_SERVER=<LICENSE_SERVER> \
    -p 50051:50051 \
    ghcr.io/ansys/geometry:<TAG>

Powershell

docker run `
    --name ans_geo `
    -e LICENSE_SERVER=<LICENSE_SERVER> `
    -p 50051:50051 `
    ghcr.io/ansys/geometry:<TAG>

Windows CMD

docker run ^
    --name ans_geo ^
    -e LICENSE_SERVER=<LICENSE_SERVER> ^
    -p 50051:50051 ^
    ghcr.io/ansys/geometry:<TAG>

Warning

When running a Windows Docker container, certain high-value ports might be restricted from its use. This means that the port exposed by the container has to be set to lower values. You should change the value of -p 50051:50051 to use a port such as -p 700:50051.

Connect to the Geometry service

After the Geometry service is launched, connect to it with these commands:

from ansys.geometry.core import Modeler

modeler = Modeler()

By default, the Modeler instance connects to 127.0.0.1 ("localhost") on port 50051. You can change this by modifying the host and port parameters of the Modeler object, but note that you must also modify your docker run command by changing the <HOST-PORT>-50051 argument.

The following tabs show the commands that set the environment variables and Modeler function.

Warning

When running a Windows Docker container, certain high-value ports might be restricted from its use. This means that the port exposed by the container has to be set to lower values. You should change the value of ANSRV_GEO_PORT to use a port such as 700, instead of 50051.

Environment variables

Linux/Mac

export ANSRV_GEO_HOST=127.0.0.1
export ANSRV_GEO_PORT=50051

Powershell

$env:ANSRV_GEO_HOST="127.0.0.1"
$env:ANSRV_GEO_PORT=50051

Windows CMD

SET ANSRV_GEO_HOST=127.0.0.1
SET ANSRV_GEO_PORT=50051

Modeler function

>>> from ansys.geometry.core import Modeler
>>> modeler = Modeler(host="127.0.0.1", port=50051)

Go to Docker containers

Go to Getting started