What about the Credit System aka C3SCoins?

Now that you are confindent with Docker, images, containers and projects, you would to use some nodes of OCCAM. For doing your computation, you need to book one (or more) node(s) through the Resource Booking System that is available on this site, look at the main menu.

A booking reservation has an associated cost, automatically calculated by the system, so you need to get a C3SCoin credit to finalize a reservation. The credit exchange capabilities embedded into the Booking System allows credits exchange to/from everyone, but usually you should ask your credits to your departmental coordinator. A list of coordinators can be found at the end of the Credit System howto.

So, first of all surf into the Resource Booking System, then contact you coordinator and ask to them some credits. If your coordinator accept your request, a credit exchange will follow; with these credits you will book the nodes you need autonomously, choosing node type, time slots and duration of the reservation.


Mandelbrot Example

An example project is provided on OCCAM's GitLab instance that can be used as a starting point for building your own project. Please find the project at https://gitlab.c3s.unito.it/bagnasco/docker-example

Please note that directly running a container is currently supported only for single-node, single-step computations. Multi-node MPI applications and pipelines need some more massaging.

First, you will need to copy all the relevant files to a directory in your machine, then write a Dockerfile to tell Docker how to build the container. In this example, the Dockerfile is provided and there is only one file, the Python script that computes the Mandelbrot set, with the rather unimaginative name of mandelbrot.py.

If you're familiar with git, you can get both the files (script and Dockerfile) by cloning this project's repository:

git clone git(at)gitlab.c3s.unito.it:bagnasco/docker-example.git
cd docker-example

Otherwise, you can simply download them with wget or curl, or even with a browser, for example

mkdir docker-example
cd docker-example
(Linux/MacOS) wget https://gitlab.c3s.unito.it/bagnasco/docker-example/raw/master/Dockerfile
(Linux/MacOS) wget https://gitlab.c3s.unito.it/bagnasco/docker-example/raw/master/mandelbrot.py
(Windows) use a browser and point to https://gitlab.c3s.unito.it/bagnasco/docker-example/raw/master/Dockerfile and save the page as Dockerfile into the docker-example directory just created
(Windows) use a browser and point to https://gitlab.c3s.unito.it/bagnasco/docker-example/raw/master/mandelbrot.py and save the page as mandelbrot.py into the docker-example directory just created

Take your time to peruse the Dockerfile before building; the full docker commands reference is at https://docs.docker.com/engine/reference/builder/.

Now you can build the image with

docker build -t gitlab.c3s.unito.it:5000/<YOURUSERNAME>/<PNAME> .

The last dot in the build command is mandatory !! You will see that Docker downloads the base image, then step-by-step does all the operations described in the Dockerfile. <username>/mandelbrot is the name you give to the image. Please replace \<YOURUSERNAME> with your OCCAM username and PNAME with your gitlab project name. Docker caches everything that can be cached, so if you change something in the Dockerfile and build again it will not, for example, download again the base image.

At this point, you can use the command docker images to see the newly-built image (as well as all other previously built images, if any), and docker run to test the container:

docker images

The output should be something like the following lines, where YOURUSERNAME and PNAME are replaced with the values used in the build command:

REPOSITORY                                       TAG                 IMAGE ID            CREATED             SIZE
gitlab.c3s.unito.it:5000/<YOURUSERNAME>/<PNAME>  latest              43d6299dbca8        2 weeks ago         240 MB

Now let's try to run it on your desktop/laptop to see docker in action:

(Linux/MacOS) docker run -ti --rm --volume $PWD:/data --workdir /data gitlab.c3s.unito.it:5000/<YOURUSERNAME>/<PNAME>
(Windows) docker run -ti --rm --volume %cd%:/data --workdir /data gitlab.c3s.unito.it:5000/<YOURUSERNAME>/<PNAME>

In our convention, the software must read and write to the current directory from which the container is launched. This is exposed inside the container by the --volume $PWD:$PWD --workdir $PWD options to the command. You can find the full docker run reference at https://docs.docker.com/engine/reference/run/.

The output should be something like


and you should find a new file mandelbrot.png in the current directory. You can pass arguments to the script, that will override the defaults defined in the Dockerfile, by adding them to the command line:

(Linux/MacOS) docker run -ti --rm --volume $PWD:/data --workdir /data <YOURUSERNAME>/<PNAME> 10 10. 101 301
(Windows) docker run -ti --rm --volume %cd%:/data --workdir /data <YOURUSERNAME>/<PNAME> 10 10. 101 301

Uploading the image to occam registry

An image registry is a store where the images can be pushed/pulled when needed; every gitlab project own a private registry useful for storing our project images and occam is able to pull from there you "bag of tools" for doing computation. So, in order to run on OCCAM, you need to push the image to the image registry.

First you will need to login to the GitLab repository, using your OCCAM username and password:

docker login gitlab.c3s.unito.it:5000

You should see something like:

Username: <Enter you USERNAME on gitlab.c3s.unito.it>
Password: <Enter you PASSWORD on gitlab.c3s.unito.it>
Login Succeded

WARNING: The gitlab web interface accept as username either the effective username or the email, but in docker login you should give in input your username, not your email!

Then you can push it with a name including the registry name and push it:

docker push gitlab.c3s.unito.it:5000/<YOURUSERNAME>/<PNAME>

If everything went well, you can go to the registry page at https://gitlab.c3s.unito.it/\<YOURUSERNAME>/\<PNAME>/container_registry and you will see your image entry. It will be named "latest": you can add version tags to your containers like <YOURUSERNAME>/<PNAME>:v1, but the "latest" tag will always be an alias for the, well, latest version built.

Please refer to the other HowTo sections to further information.

(last revision: august 2022 by Thomas Cocco)