Skip to content

Commit

Permalink
Workstation 22.04 docs update
Browse files Browse the repository at this point in the history
  • Loading branch information
assumptionsandg committed Oct 12, 2023
1 parent e08e237 commit cd8d18b
Show file tree
Hide file tree
Showing 3 changed files with 83 additions and 2 deletions.
Binary file added docs/assets/images/jupyter-notebook-interface.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
80 changes: 79 additions & 1 deletion docs/platforms/linux-workstation.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ hide:
---

### Introduction
The Linux Workstation platform provides a flexible [Ubuntu](https://ubuntu.com/) 20.04 cloud instance, with web-browser access to the graphical desktop or shell. Optionally, users may add an external IP address, which allows the instance to be accessed from a machine outside of the project using [SSH](https://en.wikipedia.org/wiki/Secure_Shell).
The Linux Workstation platform provides a flexible [Ubuntu](https://ubuntu.com/) 22.04 cloud instance, with web-browser access to the graphical desktop or shell. Optionally, users may add an external IP address, which allows the instance to be accessed from a machine outside of the project using [SSH](https://en.wikipedia.org/wiki/Secure_Shell).

The workstation instance has a cloud volume (or virtual disk) available at `/data`, which may be useful for working with large datasets. The capacity of this cloud volume is configurable when launching the platform.

Expand All @@ -23,3 +23,81 @@ The workstation instance has a cloud volume (or virtual disk) available at `/dat
### Advanced
#### Platform monitoring
A [Grafana](https://grafana.com/oss/grafana/) dashboard for system monitoring is included in the platform, and is accessible from the platforms page. General current and historical system information is visible.

#### EESSI
The [EESSI](http://www.eessi.io/docs/) suite of software is included in the Workstation appliance. This suite includes a diverse collection of toolkits and modules for research computing purposes. More details on the architecture of the EESSI suite can be found [here](http://www.eessi.io/docs/overview/).

To assess whether the EESSI suite is functioning correctly, you can run some of their demo environments avaliable in the EESSI demo [Github](https://github.com/EESSI/eessi-demo/tree/main) repository. You can clone the repository using the command below.

```git clone https://github.com/EESSI/eessi-demo.git```

As an example, we can run the TensorFlow demo environment to ensure the environment is setup correctly. It is first neccessary to source the EESSI bash environment, to do this please run the following command.

```source /cvmfs/pilot.eessi-hpc.org/versions/2021.12/init/bash```

This script will initialize the Lua modules for the Software layer in the EESSI stack and source the neccessary environment variables for you to interact with them. To assess whether the script completed successfully, you can try run the ``module avail`` command to list all modules avaliable to you in the environment. A successful initialization should result in an output resembling the one below.

```
[EESSI pilot 2021.12] $ module avail
------ /cvmfs/pilot.eessi-hpc.org/versions/2021.12/software/linux/x86_64/intel/haswell/modules/all ------
ant/1.10.8-Java-11
Arrow/0.17.1-foss-2020a-Python-3.8.2
Bazel/3.6.0-GCCcore-9.3.0
...
```
Now you have a functioning environment, you can begin experimenting with the software included in EESSI. Enter the directory of the EESSI-demo repository we cloned earlier, then enter the TensorFlow directory.

This TensorFlow project contains a demonstration 4-layer neural network model which runs against the MNIST digits dataset. You can tinker with the ``TensorFlow-2.x_mnist-test.py`` script to setup a different model architecture as you like. To run the default configuration, you can execute the ``run.sh`` script inside the directory, which should produce an evaluation output like below.

```
[EESSI pilot 2021.12] $ ./run.sh
2023-10-09 13:15:04.546828: I tensorflow/core/common_runtime/process_util.cc:146] Creating new thread pool with default inter op setting: 2. Tune using inter_op_parallelism_threads for best performance.
Epoch 1/5
1875/1875 [==============================] - 5s 3ms/step - loss: 0.2951 - accuracy: 0.9138
Epoch 2/5
1875/1875 [==============================] - 14s 7ms/step - loss: 0.1445 - accuracy: 0.9568
Epoch 3/5
1875/1875 [==============================] - 6s 3ms/step - loss: 0.1070 - accuracy: 0.9669
Epoch 4/5
1875/1875 [==============================] - 3s 2ms/step - loss: 0.0886 - accuracy: 0.9732
Epoch 5/5
1875/1875 [==============================] - 3s 2ms/step - loss: 0.0766 - accuracy: 0.9763
313/313 - 0s - loss: 0.0745 - accuracy: 0.9774
real 0m41.002s
user 2m24.151s
sys 1m54.599s
```
Guides on how to utilise EESSI further can be found [here](http://www.eessi.io/docs/using_eessi/eessi_demos/).


#### Podman

Podman is a container framework provided in the Workstation appliance for the purpose of installing, managing and developing OCI containers. We **strongly** recommend installing any software you wish to add to the your Workstation via podman, as software installed via the package manager or otherwise located outside of ``/home`` will be removed during image upgrades. In-place upgrades are not supported in the Workstation appliance as to reduce dependancy issues between migrations, instead your ``/home`` directory is kept as a seperate partition and re-mounted after the Workstation has been re-imaged.

The podman is syntatically similar to the Docker CLI. For instance, we can build and deploy a Jupyter notebook as an example using Podman and access our deployment in the web interface:

To begin, clone the Jupyter notebook docker repository and navigate to the notebook directory as below:

```https://github.com/jupyter/docker-stacks.git && cd docker-stacks/images/base-notebook```

Build the Jupyter notebook image, and select the docker.io remote when promoted by podman:

```podman build . --tag jupyter-notebook```

Query the list locally available images to ensure the Jupyter notebook built correctly:

```podman image ls | grep jupyter-notebook```

Start the Jupyter notebook container:

```podman run --name notebook -p 8888:8888 jupyter-notebook```

Once the container has finished starting Jupyter notebook will print an access link to the web interface in the console, after navigating to this link in your web browser you should see the Jupyter notebook web interface as shown below:

![Jupyter notebook web interface](/docs/assets/images/jupyter-notebook-interface.png)

As this is a base notebook it won't contain many applications for you to explore, you can find more notebooks to build in the [docker-stacks](https://github.com/jupyter/docker-stacks) repository and use the steps

If setting up the notebook didn't produce any unexpected behaviour, podman is running correctly in your Workstation appliance. For more advanced information about using podman, you can check out the docs [here](https://docs.podman.io/en/latest/).
5 changes: 4 additions & 1 deletion docs/platforms/slurm.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,4 +24,7 @@ The Slurm platform provides a multi-node HPC environment based on the [Slurm wor
#### Platform monitoring
A [Grafana](https://grafana.com/oss/grafana/) dashboard for system monitoring is included in the platform, and is accessible from the platforms page. General current and historical system information is visible.

Additionally, Open OnDemand presents monitoring dashboards for each Slurm job.
Additionally, Open OnDemand presents monitoring dashboards for each Slurm job.

#### Installing packages
To install packages in the Slurm appliance, you cannot use the `slurm` user as it has no root permissions. Instead, it becomes neccessary to use the `rocky` default user which has passwordless-sudo enabled. Azimuth will copy your public key to this user during appliance deployment meaning it will be accessible to you via SSH.

0 comments on commit cd8d18b

Please sign in to comment.