Skip to content

Doc.Installation.Docker.Linux

Jump to bottom
Joe Latessa edited this page Jun 11, 2024 · 4 revisions

Step 1: Install Docker:

  1. Install Docker: https://docs.docker.com/install/
  2. Allow your user to run docker (requires admin privileges):
sudo groupadd docker
sudo usermod -aG docker $USER

Log out and log back in.

Step 2: Download X-SCAPE

The docker container will contain only the pre-requisite environment to build X-SCAPE, but will not actually contain X-SCAPE itself. Rather, we will create a directory on our own machine with the X-SCAPE code, and share this directory with the docker container. This will allow us to build and run X-SCAPE inside the docker container, but to easily edit macros and access the output files on our own machine.

  1. Make a directory on your machine (which will be shared with the docker container), and clone X-SCAPE into it.
mkdir ~/jetscape-docker
cd ~/jetscape-docker
git clone https://github.com/JETSCAPE/X-SCAPE.git

In what follows we assume such a directory at ~/jetscape-docker. You may decide to name your directory something else, but if so please be careful to substitute your directory name appropriately in the instructions below.

  1. Create and start a docker container that contains all of the X-SCAPE pre-reqs.
docker run -it -v ~/jetscape-docker:/home/jetscape-user --name myJetscape --user $(id -u):$(id -g) jetscape/base:stable
  1. For details on the compatibility of docker image versions with X-SCAPE versions, please see the jetscape dockerhub page.

This is what the docker run command does:

  • docker run creates and starts a new docker container from a pre-defined image jetscape/base:stable, which will be downloaded if necessary.

  • -it runs the container with an interactive shell.

  • -v mounts a shared folder between your machine (at ~/jetscape-docker) and the container (at /home/jetscape-user), through which you can transfer files to and from the container. You can edit the location of the folder on your machine as you like.

  • --name (optional) sets a name for your container, for convenience. Edit it as you like.

  • --user $(id -u):$(id -g) (only needed on linux) runs the docker container with the same user permissions as the current user on your machine (since docker uses the same kernel as your host machine, the UIDs are shared). Note that the prompt will display "I have no name!", which is normal.

Note that on linux, you may want to add the option --memory to limit the amount of memory that docker is allowed to consume (by default, the available memory and CPUs are not limited on linux, since it is not run in a VM as in macOS). Some useful commands:

  • To see the containers you have running, and get their ID: docker container ls (-a to see also stopped containers)

  • To stop the container: docker stop or exit

  • To re-start the container: docker start -ai

  • To put a running container into detatched mode: Ctrl-p Ctrl-q, and to re-attach: docker attach

  • To delete a container: docker container rm

For example to exit and re-enter the docker container: [From inside the container]

exit

[Now we are outside the container]

docker container ls -a
...
docker start -ai myJetscape

[Now we are inside the container again]

You may find it useful to keep two terminals open — one inside the docker container, and one outside the container — so that you can easily execute commands either inside or outside the container, as appropriate.

Step 3: Build X-SCAPE

From inside the docker container, we can now build X-SCAPE.

cd X-SCAPE
mkdir build
cd build
cmake ..
make -j4     # Builds using 4 cores; adapt as appropriate

Step 4: Run X-SCAPE

That's it! You are now inside the docker container, with X-SCAPE and all of its prerequisites installed. You can run X-SCAPE executables or re-compile code. Moreover, since we set up the jetscape-docker folder to be shared between your host and the docker container, you can do text-editing etc. on your host machine, and then immediately build X-SCAPE in the docker container. Output files are also immediately accessible on your host machine if desired.

To test that everything is working, run an example to generate some pp events:

cd X-SCAPE/build
./runJetscape ../config/publications_config/arXiv_1910.05481/jetscape_user_PP_1910.05481.xml

This should take a couple minutes to run, and will print out a variety of information to stdout. Once done, it will produce a HepMC file test_out.hepmc in the same directory -- success!

Clone this wiki locally