Docker Desktop#

Note

If you are using Windows Subsystem for Linux (WSL), you can use AiiDAlab launch to automate much of the setup process described below. Please refer to the AiiDAlab launch guide for more information.

Important

The following steps require Docker Desktop. If you have yet to install it, please follow the instructions to install Docker Desktop.

Open the Docker Desktop app and follow these instructions to spin up an AiiDAlab container:

Fetch the AiiDAlab image#

  1. On the left sidebar, click on Images

    Docker images

  2. In the search bar at the top of the app

    • Enter one of the following AiiDAlab images:

      • aiidalab/qe - pre-configured with the Quantum ESPRESSO app (recommended)

      • aiidalab/full-stack - bare image

        Note

        We recommend the pre-configured image, as it includes much of the mechanics necessary to run a calculation on AiiDAlab. To learn more about the app, please visit the AiiDAlab Quantum ESPRESSO app documentations.

    • Select latest from the Tag dropdown menu

    • Click Pull to download the image

      Image search

    • Once downloaded, the image will appear as a new line in the list of images

      Image row

  3. Exit the search menu when done

Create a persistent volume#

Important

To avoid losing your work when the container shuts down (manually, or when the machine is turned off), it is important to mount a volume (a local storage) on the container. Associating the volume with the user directory ensures the persistence of all user data.

  1. On the left sidebar, click on Volumes

    Docker volumes

  2. Click on Create

  3. Name your volume (e.g. aiidalab_home) and click Create

    New volume

  4. Repeat the process to create a second volume (e.g. aiidalab_conda) for the conda environment

  5. Return to the Images panel

Create an AiiDAlab container#

  1. From the new image line, under actions, click ▶️ to start a container instance

    Run image

  2. In the pop-up window, expand Optional settings

    Run container

  3. You may choose to name the container for easy reference (randomly generated otherwise)

  4. Choose a local port from which to communicate with the container’s 8888 port (e.g. 8888)

  5. Associate your new volumes with the corresponding container directories

    • aiidalab_home –> /home/jovyan

    • aiidalab_conda –> /home/jovyan/.conda

  6. Click Run to start the container

Launch AiiDAlab#

  1. On the left sidebar, click on Containers

    Docker containers

  2. Click on the name of your newly-created container in the list of containers

  3. Wait for the container build process to finish

  4. When done, the log will show the following message

    Log message

  5. Click the http://127.0.0.1:8888 link at the top of the app to open AiiDAlab in the browser

    Note

    If you selected a port other than 8888, you can change the port in the URL

  6. You will now be redirected to the AiiDAlab home page