Develop on containers

This guide describes how to develop PyMAPDL features or fix bugs in a development container. The container configurations are in the .devcontainer directory.

About the MAPDL container

The local development container is based on an Ansys MAPDL image. MAPDL images cannot be made publicly available because of licensing restrictions. Each person or organization must create and maintain its own image and have a valid MAPDL license. To create an image, see Create your own MAPDL docker container.

License

Configure the image to reach your license server before starting the container. Do not commit license-server addresses or other site-specific settings.

Use a local development container

To use the local container, install the following software:

• Visual Studio Code

• Docker or an equivalent container runtime

• The Dev Containers extension

Clone the PyMAPDL repository and open it in Visual Studio Code. Open the Command Palette with Ctrl + Shift + P on Windows and Linux, or Cmd + Shift + P on macOS. Select Dev Containers: Open Folder in Container and then select PyMAPDL-DevContainer (Local).

The configuration is in the local devcontainer configuration. It builds the Dockerfile from the same directory and mounts the repository according to its docker-compose.yml file. The initial build can take several minutes while Docker downloads the base image and installs dependencies.

Customize the local development container

To use a custom MAPDL image, update the FROM instruction in the Dockerfile. Update docker-compose.yml when your image requires different volumes, ports, environment variables, or other Docker settings.

Keep site-specific changes outside your pull request. The development container files are shared project configuration.

Use GitHub Codespaces

GitHub Codespaces is disabled for the PyMAPDL repository. The repository includes separate configurations for development and documentation that you can use when setting up Codespaces in a fork or another repository:

• .devcontainer/codespaces-dev/devcontainer.json builds the development container, including its test dependencies.

• .devcontainer/codespaces-docs/devcontainer.json builds the documentation container, including its documentation dependencies.

Each configuration uses the Dockerfile in its own directory. Ensure that its base image is available to your repository and is configured for your MAPDL license before creating the codespace.

Select the appropriate configuration when you create a codespace in your fork or repository. See the Visual Studio Code Dev Containers documentation for more information.