From 8c73c9647eb4ca3753395d648e3f0f435078a2ee Mon Sep 17 00:00:00 2001 From: Aliaksandr Yakutovich Date: Mon, 19 Feb 2024 14:21:57 +0100 Subject: [PATCH 01/10] Improve the README file --- README.md | 112 ++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 88 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index a7f5128..bad7a68 100644 --- a/README.md +++ b/README.md @@ -1,57 +1,120 @@ # aiidalab-for-teaching ## Local deployment -[Install docker](https://docs.docker.com/get-docker/) desktop on your pc. -Make sure you have [git installed](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) on your pc +### Prerequisites -for windows: -open power shell and execute: +To run the AiiDAlab for teaching on your local machine, we recommnd to have Docker and Python installed. +Since the instructions depend on the operating system, please select the appropriate section below. + +#### Linux/Mac + +**Docker** +To install Docker, please follow the instructions available on the Docker website for [Linux](https://docs.docker.com/desktop/install/linux-install/) or [Mac](https://docs.docker.com/desktop/install/mac-install/). + + +**Git** +Usually, Git is already installed on Linux and Mac. +If not, please install it using the package manager of your operating system. +For instance, on Ubuntu, you can install Git by running the following command: +```bash +sudo apt update && sudo apt install git +``` + +On Mac, you can install Git using [Homebrew](https://brew.sh/): +```bash +brew install git +``` + +**Python** + +Python is also quite often pre-installed on Linux and Mac. +If this is not the case, we recommend installing Python through Conda the minimal installed named Miniconda. +The installation instructions are available on the [Conda website](https://docs.conda.io/en/latest/miniconda.html). + + +#### Windows + +**Docker** +The Docker Desktop for Windows can be installed from the [Docker website](https://docs.docker.com/desktop/install/windows-install/). + + +**Git** and **Python** + +Instead of installing Git and Python separately, we recommend installing the Windows Subsystem for Linux (WSL) and using the Ubuntu distribution. +First, you should make sure that you have [WSL 2 running](https://docs.docker.com/desktop/wsl/). +Once this is set, open PowerShell as an administrator and run the following commands: ```bash wsl --set-default-version 2 wsl --install -d ubuntu ``` -open the WSL terminal from the start menu then execute: + +After this is completed, please open the Ubuntu WSL terminal from the start menu and execute: ```bash sudo apt update && sudo apt install python3-pip -pip install aiidalab-launch start ``` -close the WSL terminal and re-open it -make sure you have [WSL 2 running](https://docs.docker.com/desktop/wsl/): -oepn a terminal in your mac/linux (or WSL for windows) and execute in a appropriate directory (e.g. your home folder or the home in the WSL terminal) +TODO: How to enable Docker from within Ubuntu WSL? + + +### Install aiidalab-launch + +To install aiidalab-launch, please run the following command in your terminal: + ```bash -git clone https://github.com/nanotech-empa/aiidalab-for-teaching.git +pip install aiidalab-launch ``` -enter the aiidalab-for-teaching folder: + + +### Get the AiiDAlab for teaching container + +At this point you can decide to either build the container locally or to use a pre-compiled image from the GitHub Container Registry (ghcr.io). +The first option is recommended if you run on a machine with a different architecture than x86_64 (e.g. ARM). + +The following sub-sections require to enter the commands in a terminal (Mac/Linux) or in the Ubuntu WSL terminal (on Windows). + +#### Pull the pre-compiled image + +To download the pre-compiled image from the GitHub Container Registry, please run the following command: + ```bash -cd aiidalab-for-teaching +docker pull ghcr.io/nanotech-empa/aiidalab-for-teaching:main ``` -Install aiidalab-launch on your PC +To rename the image to `aiidalab/teaching`, please run the following command: -execute: ```bash -pip install aiidalab-launch +docker tag ghcr.io/nanotech-empa/aiidalab-for-teaching:main aiidalab/teaching +``` + + +#### Build the image locally + +First, make sure the Docker Desktop is running. +Enter a folder where you want to keep the aiidalab-for-teaching repository (`cd /path/to/your/folder`) and run the following command: + +```bash +git clone https://github.com/nanotech-empa/aiidalab-for-teaching.git ``` -### Make sure Docker desktop is running +Then enter the repository folder (`cd aiidalab-for-teaching`) and build the container by running the following command: +execute: -To build the container locally run the following command: ```bash docker build -t aiidalab/teaching . ``` -### To use a pre-compiled docker image (e.g. if docker build fails): -run the command: +### Install aiidalab-launch + +To install aiidalab-launch, please run the following command in your terminal: + ```bash - docker pull ghcr.io/nanotech-empa/aiidalab-for-teaching:main +pip install aiidalab-launch ``` -and rename the image to aiidalab/teaching use: -```bash -docker tag ghcr.io/nanotech-empa/aiidalab-for-teaching:main aiidalab/teaching + +### Start the container ``` -#### Once the container is built/downloaded, you can create a new profile with aiidalab-launch: +Once the container is built/downloaded, you can create a new profile with aiidalab-launch: ```bash aiidalab-launch profile add teaching ``` @@ -64,6 +127,7 @@ image = "aiidalab/teaching" home_mount = "aiidalab_teaching_home" extra_mounts = [] ``` + ### To start aiidalab execute ```bash aiidalab-launch start --profile teaching From 008f1481605765bff97b7219632043b0caea30a1 Mon Sep 17 00:00:00 2001 From: Aliaksandr Yakutovich Date: Mon, 19 Feb 2024 14:26:36 +0100 Subject: [PATCH 02/10] Further improvements. --- README.md | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index bad7a68..2ce4884 100644 --- a/README.md +++ b/README.md @@ -9,10 +9,12 @@ Since the instructions depend on the operating system, please select the appropr #### Linux/Mac **Docker** + To install Docker, please follow the instructions available on the Docker website for [Linux](https://docs.docker.com/desktop/install/linux-install/) or [Mac](https://docs.docker.com/desktop/install/mac-install/). **Git** + Usually, Git is already installed on Linux and Mac. If not, please install it using the package manager of your operating system. For instance, on Ubuntu, you can install Git by running the following command: @@ -35,6 +37,7 @@ The installation instructions are available on the [Conda website](https://docs. #### Windows **Docker** + The Docker Desktop for Windows can be installed from the [Docker website](https://docs.docker.com/desktop/install/windows-install/). @@ -55,8 +58,9 @@ After this is completed, please open the Ubuntu WSL terminal from the start menu sudo apt update && sudo apt install python3-pip ``` +>>>>>>>>>>>> TODO: How to enable Docker from within Ubuntu WSL? - +<<<<<<<<<<<< ### Install aiidalab-launch @@ -112,9 +116,10 @@ To install aiidalab-launch, please run the following command in your terminal: pip install aiidalab-launch ``` -### Start the container -``` +### Configure your profile + Once the container is built/downloaded, you can create a new profile with aiidalab-launch: + ```bash aiidalab-launch profile add teaching ``` @@ -137,11 +142,12 @@ aiidalab-launch start --profile teaching aiidalab-launch stop --profile teaching ``` ### Clean-up (will delete everything): -First, remove the container: + +After the container is stopped, you can remove it by running the following command: ```bash docker rm aiidalab_teaching ``` -Also, remove the mounted volume: +Also, you should remove the volume that contains all your data. ```bash docker volume rm aiidalab_teaching_home ``` From 39868581bcf0752b705fc0cafd5cd771e529aba0 Mon Sep 17 00:00:00 2001 From: Aliaksandr Yakutovich Date: Mon, 19 Feb 2024 14:34:22 +0100 Subject: [PATCH 03/10] Add a warning section. --- README.md | 35 +++++++++++++++++++---------------- 1 file changed, 19 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 2ce4884..b2c67d2 100644 --- a/README.md +++ b/README.md @@ -8,13 +8,11 @@ Since the instructions depend on the operating system, please select the appropr #### Linux/Mac -**Docker** - +* **Docker**. To install Docker, please follow the instructions available on the Docker website for [Linux](https://docs.docker.com/desktop/install/linux-install/) or [Mac](https://docs.docker.com/desktop/install/mac-install/). -**Git** - +* **Git**. Usually, Git is already installed on Linux and Mac. If not, please install it using the package manager of your operating system. For instance, on Ubuntu, you can install Git by running the following command: @@ -27,8 +25,7 @@ On Mac, you can install Git using [Homebrew](https://brew.sh/): brew install git ``` -**Python** - +* **Python**. Python is also quite often pre-installed on Linux and Mac. If this is not the case, we recommend installing Python through Conda the minimal installed named Miniconda. The installation instructions are available on the [Conda website](https://docs.conda.io/en/latest/miniconda.html). @@ -36,31 +33,23 @@ The installation instructions are available on the [Conda website](https://docs. #### Windows -**Docker** - +* **Docker**. The Docker Desktop for Windows can be installed from the [Docker website](https://docs.docker.com/desktop/install/windows-install/). -**Git** and **Python** - +* **Git** and **Python**. Instead of installing Git and Python separately, we recommend installing the Windows Subsystem for Linux (WSL) and using the Ubuntu distribution. First, you should make sure that you have [WSL 2 running](https://docs.docker.com/desktop/wsl/). Once this is set, open PowerShell as an administrator and run the following commands: - ```bash wsl --set-default-version 2 wsl --install -d ubuntu ``` - After this is completed, please open the Ubuntu WSL terminal from the start menu and execute: - ```bash sudo apt update && sudo apt install python3-pip ``` ->>>>>>>>>>>> -TODO: How to enable Docker from within Ubuntu WSL? -<<<<<<<<<<<< ### Install aiidalab-launch @@ -86,6 +75,20 @@ To download the pre-compiled image from the GitHub Container Registry, please ru docker pull ghcr.io/nanotech-empa/aiidalab-for-teaching:main ``` +| :warning: WARNING | +|:---------------------------| +| The `docker pull` command might not work. To fix that, you need to authenticate to GitHub first: | +| ```bash | +| docker login ghcr.io -u | +| Password: | +| | +| The access token can be created here: https://github.com/settings/tokens | +| Make sure to enable the following permissions: | +| | +| * write:packages | +| * read:packages | +| * delete:packages | + To rename the image to `aiidalab/teaching`, please run the following command: ```bash From d56c7b0ec5379be2cd255901722c5b501ae12674 Mon Sep 17 00:00:00 2001 From: Aliaksandr Yakutovich Date: Mon, 19 Feb 2024 14:35:33 +0100 Subject: [PATCH 04/10] Test another warning. --- README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/README.md b/README.md index b2c67d2..dd2f66f 100644 --- a/README.md +++ b/README.md @@ -75,6 +75,9 @@ To download the pre-compiled image from the GitHub Container Registry, please ru docker pull ghcr.io/nanotech-empa/aiidalab-for-teaching:main ``` +> [!WARNING] +> asdfsdf + | :warning: WARNING | |:---------------------------| | The `docker pull` command might not work. To fix that, you need to authenticate to GitHub first: | From c2b431f37adb5bada598dcb120e2565b0c5fd8fa Mon Sep 17 00:00:00 2001 From: Aliaksandr Yakutovich Date: Mon, 19 Feb 2024 14:38:32 +0100 Subject: [PATCH 05/10] Properly format the warning section. --- README.md | 27 ++++++++++++--------------- 1 file changed, 12 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index dd2f66f..33b18b7 100644 --- a/README.md +++ b/README.md @@ -76,21 +76,18 @@ docker pull ghcr.io/nanotech-empa/aiidalab-for-teaching:main ``` > [!WARNING] -> asdfsdf - -| :warning: WARNING | -|:---------------------------| -| The `docker pull` command might not work. To fix that, you need to authenticate to GitHub first: | -| ```bash | -| docker login ghcr.io -u | -| Password: | -| | -| The access token can be created here: https://github.com/settings/tokens | -| Make sure to enable the following permissions: | -| | -| * write:packages | -| * read:packages | -| * delete:packages | +> The `docker pull` command might not work. To fix that, you need to authenticate to GitHub first: +> ```bash +> docker login ghcr.io -u +> Password: +> ``` +> The access token can be created here: https://github.com/settings/tokens +> Make sure to enable the following permissions: +> ``` +> * write:packages +> * read:packages +> * delete:packages +> ``` To rename the image to `aiidalab/teaching`, please run the following command: From af1bc72d169465e2f2b7989f6c5a9139f1e4a5c0 Mon Sep 17 00:00:00 2001 From: Aliaksandr Yakutovich Date: Mon, 19 Feb 2024 14:39:28 +0100 Subject: [PATCH 06/10] Small change. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 33b18b7..1319b9d 100644 --- a/README.md +++ b/README.md @@ -81,7 +81,7 @@ docker pull ghcr.io/nanotech-empa/aiidalab-for-teaching:main > docker login ghcr.io -u > Password: > ``` -> The access token can be created here: https://github.com/settings/tokens +> The access token can be created [here](https://github.com/settings/tokens) > Make sure to enable the following permissions: > ``` > * write:packages From ed25d686e42106c48f5df3a43956d040f4a7634e Mon Sep 17 00:00:00 2001 From: Aliaksandr Yakutovich Date: Mon, 19 Feb 2024 14:40:32 +0100 Subject: [PATCH 07/10] Finalising the work. --- README.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 1319b9d..7e4eeb7 100644 --- a/README.md +++ b/README.md @@ -60,10 +60,10 @@ pip install aiidalab-launch ``` -### Get the AiiDAlab for teaching container +### Get the aiidalab-for-teaching image -At this point you can decide to either build the container locally or to use a pre-compiled image from the GitHub Container Registry (ghcr.io). -The first option is recommended if you run on a machine with a different architecture than x86_64 (e.g. ARM). +At this point you can decide to either use a pre-compiled image from the GitHub Container Registry (ghcr.io) or to build the image locally. +The first latter approach is recommended if you run on a machine with a different architecture than `x86_64` (e.g. ARM). The following sub-sections require to enter the commands in a terminal (Mac/Linux) or in the Ubuntu WSL terminal (on Windows). @@ -81,8 +81,8 @@ docker pull ghcr.io/nanotech-empa/aiidalab-for-teaching:main > docker login ghcr.io -u > Password: > ``` -> The access token can be created [here](https://github.com/settings/tokens) -> Make sure to enable the following permissions: +> The access token can be created [here](https://github.com/settings/tokens). +> While creating it, please make sure to enable the following permissions: > ``` > * write:packages > * read:packages @@ -136,15 +136,15 @@ home_mount = "aiidalab_teaching_home" extra_mounts = [] ``` -### To start aiidalab execute +### To start the container execute: ```bash aiidalab-launch start --profile teaching ``` -### To stop execute +### To stop the container execute: ```bash aiidalab-launch stop --profile teaching ``` -### Clean-up (will delete everything): +### Clean-up (this will delete everything): After the container is stopped, you can remove it by running the following command: ```bash From 4d8c1190d385a968b8fd93b9ada93c21801b3365 Mon Sep 17 00:00:00 2001 From: Aliaksandr Yakutovich Date: Mon, 19 Feb 2024 14:47:54 +0100 Subject: [PATCH 08/10] Add TODO --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 7e4eeb7..5eb1fee 100644 --- a/README.md +++ b/README.md @@ -50,6 +50,7 @@ After this is completed, please open the Ubuntu WSL terminal from the start menu sudo apt update && sudo apt install python3-pip ``` +**TODO: Add instructions to enable docker within Ubuntu WSL.** ### Install aiidalab-launch From 134a423d0d9608b57fbcb05163a4cf42a1ba4e58 Mon Sep 17 00:00:00 2001 From: Aliaksandr Yakutovich Date: Mon, 19 Feb 2024 15:47:32 +0100 Subject: [PATCH 09/10] Update README.md Co-authored-by: Carlo Pignedoli --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 5eb1fee..992b4b9 100644 --- a/README.md +++ b/README.md @@ -64,7 +64,7 @@ pip install aiidalab-launch ### Get the aiidalab-for-teaching image At this point you can decide to either use a pre-compiled image from the GitHub Container Registry (ghcr.io) or to build the image locally. -The first latter approach is recommended if you run on a machine with a different architecture than `x86_64` (e.g. ARM). +The latter approach is recommended if you run on a machine with a different architecture than `x86_64` (e.g. ARM). The following sub-sections require to enter the commands in a terminal (Mac/Linux) or in the Ubuntu WSL terminal (on Windows). From ae084cc33aad230e8edf4bbf4d21d709f4ff5007 Mon Sep 17 00:00:00 2001 From: Aliaksandr Yakutovich Date: Mon, 19 Feb 2024 15:49:49 +0100 Subject: [PATCH 10/10] Remove duplicate of aiidalab-launch install. --- README.md | 8 -------- 1 file changed, 8 deletions(-) diff --git a/README.md b/README.md index 992b4b9..b6e1348 100644 --- a/README.md +++ b/README.md @@ -52,14 +52,6 @@ sudo apt update && sudo apt install python3-pip **TODO: Add instructions to enable docker within Ubuntu WSL.** -### Install aiidalab-launch - -To install aiidalab-launch, please run the following command in your terminal: - -```bash -pip install aiidalab-launch -``` - ### Get the aiidalab-for-teaching image