From 955a9e4f20b87c38fb4b69ed9f20d35f08e63e1a Mon Sep 17 00:00:00 2001 From: German Date: Wed, 21 Dec 2022 19:55:11 +0100 Subject: [PATCH 1/2] Hiding docker --- README.rst | 9 - doc/source/getting_started/docker.rst | 415 ------------------- doc/source/getting_started/running_mapdl.rst | 19 +- doc/source/getting_started/versioning.rst | 6 - 4 files changed, 1 insertion(+), 448 deletions(-) delete mode 100644 doc/source/getting_started/docker.rst diff --git a/README.rst b/README.rst index ba91190b7b2..c370ea5880f 100644 --- a/README.rst +++ b/README.rst @@ -237,15 +237,6 @@ you can use to send or receive arrays between MAPDL and Python. For more information, see the full documentation at `PyMAPDL Documentation `_. - -Run on Docker -~~~~~~~~~~~~~ -You can run MAPDL within a container on any OS with ``docker``. - -For information on using MAPDL within a container, see `MAPDL on Docker README -`_. - - Citing this module ------------------- If you use ``PyMAPDL`` for research and would like to cite the module diff --git a/doc/source/getting_started/docker.rst b/doc/source/getting_started/docker.rst deleted file mode 100644 index ec0e65fdb6a..00000000000 --- a/doc/source/getting_started/docker.rst +++ /dev/null @@ -1,415 +0,0 @@ -.. _pymapdl_docker: - -***************** -Docker containers -***************** -You can run MAPDL within a container on any OS using Docker and -connect to it via PyMAPDL. - -There are several situations in which it is advantageous to run MAPDL -in a containerized environment such as Docker or Singularity: - -- Run in a consistent environment regardless of the host OS. -- Portability and ease of install. -- Large-scale cluster deployment using Kubernetes -- Genuine app isolation through containerization - -Configure the Docker registry -============================= - -**Only for images in private repositories.** - -There are several Docker images hosted on the -`PyMAPDL GitHub `_ repository that you -can download using your GitHub credentials. - -Assuming that you have Docker installed, you can get started by -authorizing Docker to access this repository using a personal access -token. Create a GitHub personal access token with ``packages read`` permissions -according to `Creating a personal access token `_ - -Save that token to a file with: - -.. code:: - - echo XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX > GH_TOKEN.txt - - -This lets you send the token to Docker without leaving the token value -in your history. Next, authorize Docker to access this repository -with: - -.. code:: - - GH_USERNAME= - cat GH_TOKEN.txt | docker login ghcr.io -u $GH_USERNAME --password-stdin - - -.. _run_an_mapdl_image: - -Run an MAPDL image -=================== - -You can now launch MAPDL directly from Docker with a short script or -directly from the command line. -You can then use your host Python environment to connect to that MAPDL -instance. - -.. graphviz:: - - digraph { - node []; - subgraph cluster_frontend { - label="*HOST*"; - Python; - subgraph cluster_backend { - MAPDL; - label="*DOCKER*"; - } - } - Python -> MAPDL - MAPDL -> Python - } - -Because this image does not contain a license server, you must enter your -license server IP address in the ``ANSYSLMD_LICENSE_FILE`` environment variable. - -Additionally, you run a Docker image of PyMAPDL with: - -.. code:: pwsh - - docker run -e ANSYSLMD_LICENSE_FILE=1055@host.docker.internal --restart always --name mapdl -p 50053:50052 ghcr.io/pyansys/pymapdl/mapdl -smp > log.txt - -First time you run it, Docker logins into the *ghcr.io* registry and -pulls the image, which can take some time. -There are several images in the registry, each corresponding to a different -version of MAPDL. For Ubuntu systems (any image tagged as ``Ubuntu``), you should -use the latest version of MAPDL. - -To rerun it, you should restart the container or just delete it and run it again using: - -.. code:: pwsh - - docker stop mapdl - docker container prune - - docker run -e ANSYSLMD_LICENSE_FILE=1055@host.docker.internal --restart always --name mapdl -p 50053:50052 ghcr.io/pyansys/pymapdl/mapdl -smp > log.txt - -You can use the Docker flag ``--rm`` to automatically clean up the container -and remove the file system when the container exits. - -This creates a log file (``log.txt``) in your current directory location. - -Notice that the WSL internal gRPC port (``50052``) is being mapped to a -different Windows host port (``50053``) to avoid port conflicts with local -MAPDL instances running on the host. -You could additionally launch more Docker containers in different ports if -you want to run multiple simulations at the same time. -The module ``ansys-mapdl-core-pool`` does not work when you are connecting -to an MAPDL Docker image. - -.. note:: Ensure that your port ``50053`` is open in your firewall. - -You can provide additional command line parameters to MAPDL by simply -appending to the Docker command. -For example, you can increase the number of processors (up to the -number available on the host machine) with the ``-np`` switch. - -You should use a script file (batch ``'.bat'`` or PowerShell ``'.ps'``) -to run the preceding commands all at once. - - -Once you have launched MAPDL you should see: - -.. code:: - - Start GRPC Server - - ############################## - ### START GRPC SERVER ### - ############################## - - Server Executable : MapdlGrpc Server - Server listening on : 0.0.0.0:50052 - - - -Using ``docker-compose`` to launch MAPDL -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -You can also use ``docker-compose`` command to launch MAPDL configured in -a ``docker-compose`` file. -This is useful if you want to load an already configured environment, or -if you want to launch multiple instances of MAPDL or services. - -For you convenience, the directory `docker `_ -contains pre-configured ``docker-compose`` files that you can -use: - -* `docker-compose.yml `_: the **base** - configuration file which launch a remote instance of MAPDL which you - can connect to. - -* `docker-compose.local.yml `_: - This file is an extension of the base configuration file which launch - an Ubuntu Docker image with MAPDL installed in it. - This is useful if you want to run MAPDL locally inside this container - for example for debugging purposes. - You can connect your Visual Code instance to this container by selecting - ``Attach to a running container`` option from the command palette. - For more details visit `Attach to a running container `_. - -* `docker-compose.license_server.yml `_: - This file is an extension of the base configuration file which launch - a license server. - This is useful if you want to run MAPDL remotely and you don't have - access to a license server. - You need a valid license file to run the license server. - You can use it together with ``docker-compose.local.yml`` hence you - can connect to it the same way. - The call to this docker file should be always the last one in the - ``docker-compose`` command. For instance: - - .. code:: bash - - docker-compose -f docker-compose.yml -f docker-compose.local.yml -f docker-compose.license_server.yml up - - -.. warning:: - The license server is not intended to be used in production. - It is only intended for testing/debugging purposes. - Its access is limited to collaborators of the PyAnsys project. - If you would like to have access to the license server, contact PyAnsys support at - `pyansys.support@ansys.com `_. - - -.. _pymapdl_connect_to_MAPDL_container: - -Connect to the MAPDL container from Python -========================================== - -You can now connect to the instance with: - -.. code:: python - - >>> from ansys.mapdl.core import Mapdl - >>> mapdl = Mapdl() - -If you mapped to any other port other than 50052, you should specify -that port when connecting to MAPDL with: - -.. code:: python - - >>> mapdl = Mapdl(port=) - -Verify your connection with: - -.. code:: python - - >>> print(mapdl) - - Product: ANSYS Mechanical Enterprise - MAPDL Version: RELEASE 2021 R1 BUILD 21.0 - PyMAPDL Version: Version: 0.57.0 - - -To connect to an existing MAPDL instance, you can use the :func:`launch_mapdl() ` method with the argument ``start_instance=False``: - -.. code:: python - - from ansys.mapdl.core import launch_mapdl - - mapdl = launch_mapdl(port=50053, start_instance=False) - - -Because of the linking between host ports and Docker ports (``-p`` argument), -you do not need to specify the IP address when connecting to a local container. -However, if you are trying to connect to a WSL local distribution, you must -specify the IP address of the WSL instance (normally ``127.0.0.1``) because -no port mapping is done between both. - -Here is an example: - -.. code:: python - - from ansys.mapdl.core import Mapdl - - mapdl = Mapdl(ip='127.0.0.1', port=50053) - - -You can also specify the port and IP address using environment variables that are read when -launching the MAPDL instance: - -.. code:: bash - - export PYMAPDL_START_INSTANCE=False - export PYMAPDL_PORT=50053 - export PYMAPDL_IP=127.0.0.1 - - - -Launch Docker with UPF capabilities -=================================== - -If you want to specify a custom Python UPF routine, you must have the -environment variables ``ANS_USER_PATH`` and ``ANS_USE_UPF`` defined. The -former should be equal to the path where the UPF routines are located, and the -latter should be equal to ``TRUE``. - -In WSL, you can do this using: - -.. code:: bash - - export ANS_USER_PATH=/home/user/UPFs # Use your own path to your UPF files. - export ANS_USE_UPF=TRUE - -You can then run the Docker image with: - -.. code:: bash - - docker run -e ANSYSLMD_LICENSE_FILE=1055@host.docker.internal -e ANS_USER_PATH='/ansys_jobs/upf' -e ANS_USE_UPF='TRUE' --restart always --name mapdl -p 50053:50052 ghcr.io/pyansys/pymapdl/mapdl -smp 1>log.txt - -.. warning:: The use of UPFs with Docker images or PyMAPDL is still in the alpha state. - - - -Additional considerations -========================= - -Append MAPDL options to the container -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -In the command: - -.. code:: - - IMAGE=ghcr.io/pyansys/pymapdl/mapdl:$VERSION - docker run -e ANSYSLMD_LICENSE_FILE=$LICENSE_SERVER -p 50052:50052 $IMAGE -smp - -You can provide additional command line parameters to MAPDL by simply -appending to the Docker command. For example, you can increase the -number of processors (up to the number available on the host machine) -with the ``-np`` switch: - -.. code:: - - IMAGE=ghcr.io/pyansys/pymapdl/mapdl:$VERSION - docker run -e ANSYSLMD_LICENSE_FILE=$LICENSE_SERVER -p 50052:50052 $IMAGE -np 4 - - -For additional command line arguments please see the *Notes* section -within :func:`launch_mapdl() `. -Also, be sure to have the appropriate license for additional HPC features. - -Use ``--restart`` policy with MAPDL products -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -By default, MAPDL creates a ``LOCK`` file in the working directory when it starts -and deletes this file if it exits normally. The file is used to avoid overwriting files -such as database (DB) files or result (RST) files when starting MAPDL after an -abnormal termination. - -Because of this behavior, when using the Docker ``--restart`` flag in the ``docker run`` -command, you might enter into an infinite loop if you specify the Docker image to -reboot after an abnormal termination. For example, ``--restart always``. -Because of the presence of the ``LOCK`` file, MAPDL exits, attempting to not overwrite -the files from the previous crash, while the Docker process keeps attempting to -restart the MAPDL container (and the MAPDL process with it). - -In such cases, you should not use the ``--restart`` option. If you really need to use -this option, you can avoid MAPDL checks and create the ``LOCK`` file by starting -the process with the environment variable ``ANSYS_LOCK`` set to ``"OFF"``. - -You can do this in your ``docker run`` command: - -.. code:: bash - - docker run \ - --restart always \ - -e ANSYSLMD_LICENSE_FILE=1055@$LICENSE_SERVER \ - -e ANSYS_LOCK="OFF" \ - -p 50052:50052 \ - $IMAGE - - -Get useful files after abnormal termination -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -In some cases, the MAPDL container might crash after the MAPDL process experiences an -abnormal termination. In these cases, you can retrieve log files and output files using -tools that Docker provides. - -First, get the Docker container name: - -.. code:: pwsh - - PS docker ps - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - c14560bff70f ghcr.io/pyansys/pymapdl/mapdl:v22.2.0 "/ansys_inc/ansys/bi…" 9 seconds ago Up 8 seconds 0.0.0.0:50053->50052/tcp mapdl - -To appear in ``docker ps``, the container should be running. - -You can then use the ``name`` in the following command: - -.. code:: pwsh - - PS docker exec -it mapdl /bin/bash - -This command executes the command shell (``/bin/bash``) of the container and attaches your current terminal to it (interactive ``-it``). - -.. code:: pwsh - - PS C:\Users\user> docker exec -it mapdl /bin/bash - [root@c14560bff70f /]# - -Now you can enter commands inside the Docker container and navigate inside it. - -.. code:: pwsh - - PS C:\Users\user> docker exec -it mapdl /bin/bash - [root@c14560bff70f /]# ls - anaconda-post.log cleanup-ansys-c14560bff70f-709.sh file0.err file1.err file1.page file2.out file3.log home media proc sbin tmp - ansys_inc dev file0.log file1.log file2.err file2.page file3.out lib mnt root srv usr - bin etc file0.page file1.out file2.log file3.err file3.page lib64 opt run sys var - -You can then take note of the files you want to retrieve. For example, the error and output files (``file*.err`` and ``file*.out``). - -Exit the container terminal using ``exit``: - -.. code:: pwsh - - [root@c14560bff70f /]# exit - exit - (base) PS C:\Users\user> - -You can copy the noted files using this script: - -.. code:: pwsh - - docker cp mapdl:/file0.err . - docker cp mapdl:/file1.err . - docker cp mapdl:/file1.out . - -If you want to retrieve multiple files, the most efficient approach is to get back inside the Docker container: - -.. code:: pwsh - - PS C:\Users\user> docker exec -it mapdl /bin/bash - [root@c14560bff70f /]# - -Create a folder where you are going to copy all the desired files: - -.. code:: pwsh - - [root@c14560bff70f /]# mkdir -p /mapdl_logs - [root@c14560bff70f /]# cp -f /file*.out /mapdl_logs - [root@c14560bff70f /]# cp -f /file*.err /mapdl_logs - [root@c14560bff70f /]# ls mapdl_logs/ - file0.err file1.err file1.out file2.err file2.out file3.err file3.out - -Then copy the entire folder content at once: - -.. code:: pwsh - - docker cp mapdl:/mapdl_logs/. . - diff --git a/doc/source/getting_started/running_mapdl.rst b/doc/source/getting_started/running_mapdl.rst index e90d84d2b24..7d9bcdcafe1 100644 --- a/doc/source/getting_started/running_mapdl.rst +++ b/doc/source/getting_started/running_mapdl.rst @@ -26,7 +26,7 @@ installer options can change, see the following figure for reference. If you want to avoid having to install MAPDL locally, you can use Docker. This is especially convenient if you are using a non-supported platform such -as MacOS. For more information, see :ref:`pymapdl_docker`. +as MacOS. You can also download and try `Ansys Student Versions `_. A Student Version is valid during a calendar year with limited capabilities. For @@ -136,20 +136,3 @@ If you have MAPDL installed on your local host, you can use the :func:`launch_mapdl() ` method to both start and connect to MAPDL. If you have any problem launching PyMAPDL, see :ref:`debugging_launch_mapdl`. - -Connect to a dockerized MAPDL session -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If you work with Docker, for example you use the -`docker-compose.yml `_ file provided in the -directory `docker `_, then you must connect to the -MAPDL instance running on the Docker container as if it was a remote MAPDL -instance. However, because the ports are exposed to the host via the ``ports`` field -in the `docker-compose.yml `_ file, you can connect -to this MAPDL instance without specifying the IP address of the Docker container. - -If you are using the local configuration specified in the -`docker-compose.local.yml `_ file, -after attaching your Visual Code instance, you can work with MAPDL as if it were local. -This means that you can launch MAPDL instances using :func:`launch_mapdl() `. - diff --git a/doc/source/getting_started/versioning.rst b/doc/source/getting_started/versioning.rst index 87c6b543637..5f74a92ba91 100644 --- a/doc/source/getting_started/versioning.rst +++ b/doc/source/getting_started/versioning.rst @@ -16,12 +16,6 @@ Ansys 2020 R1 and later support the latest `gRPC interface `_, allowing for remote management of MAPDL with rapid streaming of mesh, results, and files from the MAPDL service. -This interface also allows to work with a Docker image. -If you have the applicable license, you can install and use -MAPDL within Docker, enabling you -to run and solve even on officially unsupported platforms like Mac -OS. For more information visit :ref:`pymapdl_docker`. - Legacy interfaces ~~~~~~~~~~~~~~~~~ From 25891ffce55e71a9f902fdd965fd3d23ed5bdadf Mon Sep 17 00:00:00 2001 From: German Date: Thu, 22 Dec 2022 09:57:45 +0100 Subject: [PATCH 2/2] Removing docker from toctree --- doc/source/getting_started/index.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/doc/source/getting_started/index.rst b/doc/source/getting_started/index.rst index 692a97b73fa..6ec7b117498 100644 --- a/doc/source/getting_started/index.rst +++ b/doc/source/getting_started/index.rst @@ -16,7 +16,6 @@ For more information on getting a licensed copy of Ansys, visit learning versioning running_mapdl - docker wsl using_julia faq