Improve the README file (#18)

Co-authored-by: Carlo Pignedoli <[email protected]>

README.md

@@ -1,57 +1,121 @@
 # 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: Add instructions to enable docker within Ubuntu WSL.**
+
+
+### 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 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).
+
+#### Pull the pre-compiled image
+
+To download the pre-compiled image from the GitHub Container Registry, please run the following command:
+
 ```bash
-git clone https://github.com/nanotech-empa/aiidalab-for-teaching.git
+docker pull ghcr.io/nanotech-empa/aiidalab-for-teaching:main
 ```
-enter the aiidalab-for-teaching folder:
+
+> [!WARNING]
+> The `docker pull` command might not work. To fix that, you need to authenticate to GitHub first:
+> ```bash
+> docker login ghcr.io -u <github-username>
+> Password: <your-token>
+> ```
+> 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
+> * delete:packages
+> ```
+
+To rename the image to `aiidalab/teaching`, please run the following command:
+
 ```bash
-cd aiidalab-for-teaching
+docker tag ghcr.io/nanotech-empa/aiidalab-for-teaching:main aiidalab/teaching
 ```
 
-Install aiidalab-launch on your PC
 
-execute:
+#### 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
-pip install aiidalab-launch
+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:
-```bash
- docker pull ghcr.io/nanotech-empa/aiidalab-for-teaching:main
-```
-and rename the image to aiidalab/teaching use:
+### Install aiidalab-launch
+
+To install aiidalab-launch, please run the following command in your terminal:
+
 ```bash
-docker tag ghcr.io/nanotech-empa/aiidalab-for-teaching:main aiidalab/teaching
+pip install aiidalab-launch
 ```
-#### Once the container is built/downloaded, you can create a new profile with aiidalab-launch:
+
+### Configure your profile
+
+Once the container is built/downloaded, you can create a new profile with aiidalab-launch:
+
 ```bash
 aiidalab-launch profile add teaching
 ```
@@ -64,20 +128,22 @@ image = "aiidalab/teaching"
 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):
-First, remove the container:
+### Clean-up (this will delete everything):
+
+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
 ```