Using rust_code_server

The rust_code_server environment provides a pre-configured development environment based on the VS Code editor, accessible from your web browser. It is the recommended route if you want to get a working environment with minimal effort on an x86_64 system.

Setting up Docker or Podman

On Linux, you should first install one of Docker Engine or Podman, if you have not done so already. Click the names in the previous sentence to get to the recommended setup instructions.

If you are unfamiliar with containers, Docker can be significantly easier to install and is a lot more documented on the Internet, so it would be the author’s recommendation for beginners. On its side, Podman is built around a much more sensible security model, which leads among other things to better handling of file permissions. This is good for everyday use, but not essential for this course.

While containers are a Linux-native technology, they can be used on Windows and macOS via Docker Desktop, which combines Docker Engine with a hidden Linux virtual machine running in the background, and takes care of configuring this VM in a suitable way as docker commands are run on the host. While you can also use Docker Desktop on Linux, we advise against doing so as it adds more complexity and failure modes to your container runtime for no good reason.

To repeat the warning on the previous page, the rust_code_server container image is not compatible with Apptainer and Singularity. If you are in an environment which only supports this container runtime, like some computing clusters do, we advise that you either use the rust_light image or ask the system administrator to set up a local installation.

After installing a container runtime, you may need to do a little bit of extra system configuration to make the container runtime usable by non-root users (check the installation instructions linked above). Then you should be able to run a test container that prints a hello world message.

Please pick your container runtime below to see the appropriate command for this test:

docker run hello-world

Downloading the exercises source code

You may have been directed to this documentation some time ahead of the course, at a point where the material may not be fully finalized yet. To allow for further material evolution and let you save your work across container runtime shutdowns, we distribute the exercises’ source code via a separate archive that you should unpack somewhere on your machine. The resulting directory will then be mounted inside of the container.

Provided that the curl and unzip utilities are installed, you can download and unpack the source code in the current directory using the following sequence of Unix commands:

if [ -e exercises ]; then
    echo "ERROR: Please move or delete the existing 'exercises' subdirectory"
else
    curl -LO https://numerical-rust-cpu-81b2c3.pages.in2p3.fr/setup/exercises.zip  \
    && unzip exercises.zip  \
    && rm exercises.zip
fi

The following steps will assume that you are in the directory where the archive has been extracted, as if you just ran the sequence of commands above (an exercises/ subdirectory should be present in the output of the ls command).

Starting the container

Now that you have a working container runtime and the exercises’ source code, you should be able to run a container based on the development environment. We will need to change a few things with respect to the default configuration of docker run and podman run:

  • For interactive use, we will want to follow the container’s standard output and be able to interact with it using our terminal. This can be done using the -it pair of options.
  • Keeping around containers after they stop like Docker and Podman do by default is a very effective way to accidentally run out of disk space, so it is a good idea to automatically delete the container after use via the --rm option.
  • Our code editing environement uses an HTTP server that listens on port 8080 of the container. We must allow local web browsers to connect to it, but not expose it to other machines on your local network, as this could allow hackers to take control of your machine. With both Docker and Podman, this can be achieved by using the --publish 127.0.0.1:8080:8080 port forwarding configuration.
  • Finally, we need to mount the exercises material into the container so that it can be used inside. This can be done using the -v "$(pwd)/exercises":/home/jovyan/exercises option.
    • If you use Docker on a Linux distribution from the Red Hat family (RHEL, Alma, Rocky, Fedora…), which come with SELinux enabled by default, then you need to add a :Z suffix at the end of this option to let your container actually access the bind mount under SELinux’ watch. This option is not required on other Linux distributions but shouldn’t hurt either, therefore we make it part of the officially recommended command line.
    • If you use Podman, then you should add an :U suffix at the end of this option so that non-privileged users inside of the container get write access to the code.

Putting this all together, we get the following Docker and Podman command lines:

docker run -it --rm --publish 127.0.0.1:8080:8080  \
           -v "$(pwd)/exercises":/home/jovyan/exercises:Z  \
           gitlab-registry.in2p3.fr/grasland/numerical-rust-cpu/rust_code_server:latest

If you get an error message about network port 8080 already being in use, it likely means that another software on your machine (such as Jupyter) is already listening for network connections on port 8080. The easiest fix1 for this problem is for you to track down and close the offending software. This is most easily done with the help of tools that tell you which software is listening to which network port, like ss -tnlp on Linux.

Once you solve these TCP port allocation issues, you will get a few lines of output notifying you that code-server is ready to serve HTTP requests. Before that, there will be a message along these lines…

### Use the following password: xxxxxxxxxxxxxxxxxxxxxxxx

…where xxxxxxxxxxxxxxxxxxxxxxxx is a string of hexadecimal digits. Copy this string into your clipboard, then point your web browser to the http://127.0.0.1:8080 URL, and paste the password when asked to. Once that is done, you should land into a browser-based version of VSCode.

However, depending on which container runtime environment you are using, this code editor may not be fully functional yet, and you may need one last setup step to make it work.

Fixing up file permissions

One drawback of using containers on Linux is that the users of the containerized system do not match those of your local system. This causes all sorts of file access permission problems when sharing files between the container and the host. Docker and Podman handle this a little differently.

With Docker, you are responsible for changing the permissions of the directories that you mount inside of the container, so that the user inside of the container can access it.

To do this, you will need to check the output of your previous docker run command, and look for a line like this right after the “Use the following password” line…

### If using Docker, mounted files must be chown'd to uuuu:gggg

…where uuuu and gggg are the numerical user and group IDs (UID and GID) of the user running the code editor inside of the container. Take note of these numbers.

You will then be able to set up the file permissions of the exercises directory in the required way by running the sudo chown -R uuuu:gggg exercises command, where uuuu and gggg are the UID and GID acquired above.

Once this is done, the code editor inside of the Docker container will become able to modify files in the exercises/ directory, while your user on the host will momentarily lose the ability to do so.

At the end of the course, with both Docker and Podman, you will need to restore the original file permissions in order to be able to manipulate the exercises/ directory normally again. This can be done by running the following command:

sudo chown -R $(id -u):$(id -g) exercises/

Suggested workflow

The suggested workflow during the course is for you to have this course’s handouts opened in one browser tab, and the code editor opened in another tab. If your screen is large enough, two browser windows side by side will provide extra comfort.

After performing basic Visual Studio Code configuration, I advise opening a terminal, which you can do by showing the bottom pane of the code editor using the Ctrl+J keyboard shortcut.

You would then direct this terminal to the exercises directory if you’re not already there…

cd ~/exercises

And, when you’re ready to do the exercises, start running cargo run with the options specified by the corresponding course material.

  1. If you cannot easily close the software that is currently listening to port 8080, a more complex but more flexible alternative is to remove the host port of the --publish option, so that it becomes 127.0.0.1::8080. In this alternate configuration, Docker/Podman will not simply map port 8080 of the container to port 8080 on the host, but instead allocate a random host port and map it to port 8080 of the container. After the container starts, you will be able to use docker ps/podman ps to figure out which host port has been allocated for this purpose. This will then allow you to access the code editor by replacing the 8080 in the normal http://127.0.0.1:8080 code editor URL with the port number which Docker/Podman allocated to your container. ↩