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.
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
If you're familiar with git, you can get both the files (script and Dockerfile) by cloning this project's repository:
git clone :bagnasco/docker-example.git
Otherwise, you can simply download them with wget or curl, or even with a browser, for 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:
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>
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)