AiiDAlab launch

Important

The following steps require a local installation of Docker. You can verify your Docker installation by running docker run hello-world in the terminal.

AiiDAlab launch is a thin Docker wrapper which takes care of all the prerequisites to run the AiiDAlab Docker image. It helps to manage multiple AiiDAlab profiles, each with its own home directory for persistent storage, and allows to easily switch between them. To use AiiDAlab launch, please follow these steps:

1. Install AiiDAlab launch using one of the following methods:

   • pipx (recommended)

     • Install pipx, then run

       pipx install aiidalab-launch

     Note

     We recommend using pipx to install AiiDAlab launch, as it creates an isolated environment for the application, avoiding potential conflicts with other Python packages. If you run into issues, please use pip (see below).

   • pip (requires a Python installation)

     • Install Python if not already available, then run

       pip install aiidalab-launch

2. Set up a new profile using one of the following images:

   • AiiDAlab pre-configured with the Quantum ESPRESSO app (recommended)

     aiidalab-launch profile add --image aiidalab/qe:latest aiidalab
     

     Tip

     We recommend this 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.

   • Bare AiiDAlab (no pre-installed apps)

     aiidalab-launch profile add --image aiidalab/full-stack:latest aiidalab
     

   At the prompt, enter n to skip editing the profile settings.

3. Start AiiDAlab with

   aiidalab-launch start -p aiidalab
   

4. Follow the URL on the screen to open AiiDAlab in the browser

Profile Management

As shown above, you can manage multiple profiles in AiiDAlab launch, e.g., with different home directories or ports. For more information, run

aiidalab-launch profile --help

You can inspect the status of all configured AiiDAlab profiles with

aiidalab-launch status

Tip

For more detailed help, run

aiidalab-launch --help