Linux Docker container#

Note

The Linux Geometry service (Core Service) is only available starting from Ansys 2025R2 (version 252). Earlier releases are not supported on Linux.

Docker for Linux containers#

Ensure that Docker Engine is installed on your Linux machine. Once installed, no additional configuration is required to run Linux Docker containers.

Build or install the Geometry service image#

There are two options for installing the PyAnsys Geometry image:

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 Linux 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:

    GH_USERNAME=<my-github-username>
cat 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:core-linux-latest

Build the Geometry service Linux container#

The Geometry service Docker container can be easily built by using the provided Python build script or manually from the Dockerfiles in the repository.

Inside the repository’s docker folder, the relevant Dockerfiles are:

  • linux/coreservice/Dockerfile: Builds the Linux Core Service image (.NET 8, for Ansys 2025R2 up to 2026R2).

  • linux/coreservice/Dockerfile.net10: Builds the Linux Core Service image (.NET 10, for Ansys 2027R1 and newer).

Prerequisites#

Build from available Ansys installation#

To build your own image based on your local 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_linux.py

    When prompted, choose how to specify the Ansys installation:

    • Option 1 - Auto-detect: scans AWP_ROOT* environment variables for compatible installations (2025R2 or newer) and lets you select one.

    • Option 2 - Manual: prompts you to enter the version number (for example, 252 for 2025R2) and the full path to the installation (for example, /ansys_inc/v252).

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             core-linux-latest  ............   X seconds ago    Y.ZZGB
>>> ......                             ......             ............   ..............   ......

Build the Docker image from available binaries#

Prior to building your image, follow these steps:

Note

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

  • Move the ZIP file to the location of the 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:core-linux-latest .

  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             core-linux-latest  ............   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:

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

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.

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

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

$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

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

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.

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.

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.

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

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

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

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.

export ANSRV_GEO_HOST=127.0.0.1
export ANSRV_GEO_PORT=50051

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

SET ANSRV_GEO_HOST=127.0.0.1
SET ANSRV_GEO_PORT=50051

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

Go to Docker containers

Go to Getting started