diff --git a/doc/changelog.d/958.documentation.md b/doc/changelog.d/958.documentation.md new file mode 100644 index 0000000000..9d643d2237 --- /dev/null +++ b/doc/changelog.d/958.documentation.md @@ -0,0 +1 @@ +Updated Docker image \ No newline at end of file diff --git a/doc/source/getting_started/index.rst b/doc/source/getting_started/index.rst index fe9fca8a61..8483755917 100644 --- a/doc/source/getting_started/index.rst +++ b/doc/source/getting_started/index.rst @@ -93,3 +93,167 @@ To launch PyPrimeMesh, use this code: with prime.launch_prime() as prime_client: model = prime_client.model +Launching PyPrimeMesh through docker +------------------------------------ + +Ansys Prime Server is capable of being launched through docker. +Docker is an open platform for developing, shipping, and running apps in a containerized way. +Containers are standard units of software that package the code and all its dependencies. +Hence, the app runs quickly and reliably from one computing environment to another. + +Ansys Prime Server can be built as a Linux Docker container. +Hence, you should have a linux machine to run the Ansys Prime Server. + +Docker for Linux containers +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +To run the Linux Docker container for the Ansys Prime Server, +ensure that you follow these steps when installing the Docker: + +1. Install `Docker Engine `_. + +2. Restart your machine and start Docker Engine after completing the installation. + +Your Docker engine supports running Linux Docker containers, you can build or install the Ansys Prime Server image. + +.. note:: +Ansys Prime Server uses Intel MPI library for performing meshing operations. Intel MPI library requires NUMA support. +Docker desktop allows to run linux containers on windows using WSL. Existing Linux distributions used for WSL do not typically support NUMA. +It is expected that a custom Linux distribution would be required for WSL to run the Ansys Prime Server container to support NUMA. +Ansys does not recommend you to run the Ansys Prime Server image without NUMA support. + +Build or install the Ansys Prime Server image +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can install the Ansys Prime Server image in the following ways: + +• Download it from the GitHub Container Registry. + +• Build the Ansys Prime Server Linux container. + + +GitHub container registry +^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. note:: +You should have write access to the repository or should be a members of the Ansys organization. + +After installing Docker on your machine, follow these steps to download the Linux Docker container +for the Ansys Prime Server and install this image. + +1. Download the Docker image from the `PyPrimeMesh repository `_ on GitHub using your GitHub credentials. +2. Use a GitHub personal access token with permission for reading packages to authorize Docker to access the PyPrimeMesh repository. For more information, see `Managing your personal access tokens `_ in the GitHub documentation. +3. Save the token to a file using this command: + + .. code-block:: pycon + + echo XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX > GH_TOKEN.txt + +4. Authorize Docker to access the repository and run the commands for your OS. + + **Linux:** + + .. code-block:: pycon + + setenv GH_USERNAME + cat GH_TOKEN.txt | docker login ghcr.io -u $GH_USERNAME --password-stdin + +5. Pull the Ansys Prime Server locally using Docker using the following command: + + .. code-block:: pycon + + docker pull ghcr.io/ansys/prime:25.1.0 + + +Build the Ansys Prime Server linux container +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +You can build the Ansys Prime Server Docker containers from the PyPrimeMesh repository docker folder. +The docker folder has the linux/Dockerfile that builds the Linux-based Docker image. + +.. note:: + Ansys Prime Server does not support building windows-based docker images. + +You can build the docker image file as follows: + +• **Build from available Ansys installation**: Builds the Docker image using the Ansys installation available in the machine where the Docker image is being built. + +Prerequisites +'''''''''''''' + +Ensure that Docker is installed in your machine. If you do not have Docker available, see :ref:`Docker for Linux containers `. + + +Build from available Ansys installation +'''''''''''''''''''''''''''''''''''''''' + +To build your own image from your Ansys installation, follow these instructions: + +1. Go to the Docker folder in your local PyPrimeMesh repository. + +2. Execute the script with the following command (no specific location needed): + + .. code-block:: pycon + + python build_docker_linux.py + +For example, + + .. code-block:: pycon + + $AWP_ROOT251/commonfiles/CPython/3_10/linx64/Release/python/bin/python build_docker_linux.py $AWP_ROOT251 + +3. Check that the image has been created successfully. + +You can view the docker image created with latest tag as follows: + +.. figure:: ../images/docker_image.png + :width: 800pt + :align: center + +Launch the Ansys Prime Server +'''''''''''''''''''''''''''''' + +Ansys Prime Server can be launched using the PyPrimeMesh launcher. +You should set the following mandatory environment variable for launching the Ansys Prime Server: + +- PYPRIMEMESH_LAUNCH_CONTAINER: Launches the Ansys Prime Server form the PyPrimeMesh container. + +- PYPRIMEMESH_IMAGE_TAG: Latest version of the Ansys Prime Server docker image. + +- ANSYSLMD_LICENSE_FILE: License server required for launching the Ansys Prime Server. + +Setting the environment variable +''''''''''''''''''''''''''''''''' + +Define the following general environment variables prior to using the Ansys Prime Server launcher. + +**Linux** + + .. code-block:: pycon + + export PYPRIMEMESH_LAUNCH_CONTAINER=1 + export PYPRIMEMESH_IMAGE_TAG= + export ANSYSLMD_LICENSE_FILE= + +.. note:: + Docker image creation is supported from 2025 R1 version. + +Launching Ansys Prime Server +'''''''''''''''''''''''''''''' + +Ansys Prime Server can be launched as follows: + +.. code-block:: pycon + + >>> from ansys.meshing import prime + >>> client = prime.launch_prime() + >>> model = client.model + + + + + + + + + diff --git a/doc/source/images/docker_image.png b/doc/source/images/docker_image.png new file mode 100644 index 0000000000..10b5f16061 Binary files /dev/null and b/doc/source/images/docker_image.png differ diff --git a/doc/styles/config/vocabularies/ANSYS/accept.txt b/doc/styles/config/vocabularies/ANSYS/accept.txt index 2b3af588d6..2187858b64 100644 --- a/doc/styles/config/vocabularies/ANSYS/accept.txt +++ b/doc/styles/config/vocabularies/ANSYS/accept.txt @@ -20,6 +20,7 @@ ignore_self_proximity IGA [Ii]sogeometric JTOpen +[Ll]inux [Ll]ucid Material Point Manager [Mm]eshedgeodesic diff --git a/docker/README.md b/docker/README.md index e69de29bb2..1147106230 100644 --- a/docker/README.md +++ b/docker/README.md @@ -0,0 +1,15 @@ +Create your own Ansys Prime Server Docker container +=================================================== + +To learn how to build your own Ansys Server Docker container, see +`Guide to building the Linux Docker container `_. + +If you have your own Ansys installation, you can build a Docker container that uses your installation. + +To do this, download the Python script `build_docker_linux.py `_ and run it from the command line: + +.. code-block:: pycon + + python build_docker_linux.py + +If you have any problems, open a `GitHub Issue `_.