From a8044814f5e0d4f357f70e9447f71c8a590f6b5b Mon Sep 17 00:00:00 2001 From: Aliaksandr Yakutovich Date: Mon, 19 Feb 2024 15:53:11 +0100 Subject: [PATCH] Improve the README file (#18) Co-authored-by: Carlo Pignedoli --- README.md | 128 +++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 97 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index a7f5128..b6e1348 100644 --- a/README.md +++ b/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 +> Password: +> ``` +> 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 ```