Develop on a container#

This guide guides you on how to develop PyMAPDL features or fix bugs using a remote container or Codespaces. The files for setting up the container can be found in the .devcontainer directory.

About the MAPDL container#

Because MAPDL software is not open source, the GPL license does not allow to distribute a docker container to users. Having a docker container with MAPDL installed is a requirement to use any of the development methods mentioned on this section. If you want to build your own docker image, visit the following link Create your own MAPDL docker container.

Develop on a remote container#

Note

If you are an Ansys employee or collaborator and want to use this development method, please email PyAnsys Core team.

To use a remote container, you must install:

VS Code
Docker software or equivalent. It is recommended to use Windows Subsystem Linux (WSL) backend to run Linux docker containers. See Developing inside a Container Getting started for more information.
Remove Development VS Code extension pack

As mentioned before, you must have your own Docker image with MAPDL installed locally available or hosted in an online registry, i.e. GitHub ghcr.io. For the purpose of this document, assume your image is hosted at ghcr.io/myaccount/mapdlimage:mytag.

You must then modify the file docker-compose.yml with your custom image:

ports:
   - '50052:50052'
   - '50055:50055'
image: 'ghcr.io/myaccount/mapdlimage:mytag'
user: "0:0"
volumes:

Warning

Also you might need to change some environment variables or Docker options to adjust to your image configuration. Be careful to not commit those changes in your PRs.

You can now open the current folder (or PyMAPDL repository) using ctr/cmd + shift + p to open the VSCode Command palette. Then select Dev Containers: Open Folder in Container. Because the configuration is available in .devcontainer directory, VS Code will automatically launch the MAPDL container with the desired configuration.

You can now work normally, but you will be, in fact, working from inside the container. Because VSCode mount the local directory into the docker container, you don’t lose your changes if accidentally delete your container. However, this mounting process might have a significant impact on the container performance, especially noticeable if you are using MacOS. You can avoid that by cloning the repository inside the container. Visit Quick start: Open a Git repository or GitHub PR in an isolated container volume for more information.

License#

As mentioned before, you must have a valid license to run MAPDL. When you launch the container, the file script.sh automatically checks if the environment variable ANSYSLMD_LICENSE_FILE exists. This environment variable sets the port and IP address of the license server.

If you do not have set this environment variable before launching the container, you are prompt to enter your license server port and address.

You can set your license using the environment variable ANSYSLMD_LICENSE_FILE from the terminal before launching VS Code. This is recommended if you are using Windows OS. For example, if you have a license server at the address 123.45.67.89, you can set the license using:

$env:ANSYSLMD_LICENSE_FILE = '1055@123.45.65.89'
code . # launch VS Code

And then open the folder in the container using the Command palette.

Develop on Codespaces#

Codespaces is a virtual delopment environment provided by GitHub. You can launch a container which all the required tools and start to work in couple of minutes. This is an easy way to get started with PyMAPDL development.

Warning

This method is only applicable and allowed to Ansys employees or collaborators. If you are an Ansys employee and wants use this development method, please email PyAnsys Core team.