Hands-on initial setup
Please begin by creating a subdirectory called
your machine and cloning the hands-on exercise repositories into it:
mkdir mochi-tutorial cd mochi-tutorial git clone https://github.com/mochi-hpc-experiments/margo-tutorial-exercises.git git clone https://github.com/mochi-hpc-experiments/thallium-tutorial-exercises.git cd ..
The next step is to set up a Mochi development environment. The most straightforward way to do this is by creating a Docker container using an image that is preconfigured for use with the Mochi tutorial hands-on exercises. This method is documented as Option 1 below. If you prefer to use native environment, please skip to Option 2.
Option 1 (preferred): create a development environment using Docker
The Docker instructions here rely on a pre-built container image that was built for x86_64 platforms. If your host machine has a different CPU architecture (for example, an Apple M1) then you may need to create your own image from scratch to ensure that the tutorial environment works correctly. Please see the instructions for building a Docker image from scratch for more information on how to build an image appropriate for your architecture.
If you are not sure about your host CPU architecture, one symptom of
using a mismatched image is a
WARNING: The requested image's platform does
not match the detected host platform message when you run the
run command below.
You need to first have Docker installed on your machine; please see the Docker installation instructions for your platform. Once Docker is installed, you can use the following commands to download a preconfigured image:
docker pull carns/mochi-tutorial:latest docker tag carns/mochi-tutorial:latest mochi-tutorial
The following run command will instantiate a new container from the mochi-tutorial image. The container will have its name set to “mt1” (short for “mochi tutorial 1”).
The container is configured to run indefinitely in detached mode and allow login for the “mochi” user with no password.
The run command will also map the
mochi-tutorial directory created in
the previous section to the
/home/mochi/mochi-tutorial directory within
the container for convenience. This will allow you to edit the code with your
editor of choice outside the container, and jump into the container to build
the code and run it (you can also choose to edit the code directory inside
the container using Vim if you prefer).
docker run --detach --name mt1 --volume $(pwd)/mochi-tutorial:/home/mochi/mochi-tutorial mochi-tutorial
Once the container is running, you can open a shell on it using the following command.
docker exec -it mt1 /bin/bash
From the container’s command prompt you should be in the
with subdirectories available for
mochi-spack-packages, and the
mochi-tutorial directory that is mapped to your host machine and populated with
tutorial exercise files.
> docker exec -it mt1 /bin/bash mochi@d3c9c489a2c1:~$ ls mochi-spack-packages mochi-tutorial spack mochi@d3c9c489a2c1:~$ ls mochi-tutorial margo-tutorial-exercises thallium-tutorial-exercises
We recommand that you open multiple shells while following these exercises, so that you can build the code, run a server and run a client in different terminals
You can use the following commands to stop and restart the “mt1” container.
docker stop mt1 docker start mt1
If you need more detailed instructions or want to build the docker image yourself from its Dockerfile recipe, please refer to these instructions.
Option 2: create a development environment manually
Spack setup and administration is beyond the scope of this tutorial; please do not use this option unless you already have an existing Spack configuration that you are comfortable using.
If you have Spack already installed and setup on your machine, simply make sure that you have the Mochi namespace available for Spack to use. This can be done as follows.
git clone https://github.com/mochi-hpc/mochi-spack-packages.git spack repo add mochi-spack-packages
What’s next ?
You are now ready to carry on with either the Margo exercises or the Thallium exercises. Choose one depending on your preferred programming language (C or C++ respectively).