Build the X-SCAPE framework
(1) Download school material
We will use code from several git repositories throughout the course of the school, which you will run in a controlled software environment (docker). Create a single directory to store all materials from the school:
mkdir jetscape-docker
cd jetscape-dockerIn 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 remainder of the instructions.
Then download several pieces of software from git:
git clone https://github.com/JETSCAPE/X-SCAPE.git git clone https://github.com/JETSCAPE/SummerSchool2023.git
Additionally, download a few external physics packages:
cd X-SCAPE/external_packages
./get_3dglauber.sh
./get_music.sh
./get_iSS.shNow please make sure all the code packages are already in the correct place on your computer. You should have a jetscape-docker folder under your home directory. Try to list the folders inside jetscape-docker with the following command,
ls ~/jetscape-dockerand you should see X-SCAPE and SummerSchool2023 present. If you list folders inside ~/jetscape-docker/X-SCAPE/external_packages with
ls ~/jetscape-docker/X-SCAPE/external_packagesyou should see 3dMCGlauber, music and iSS folders present. They are modules needed for the Hydro Session.
(2) Install docker
Docker is a software tool that allows one to deploy an application in a portable environment. A docker "image" can be created for the application, allowing any user to run a docker "container" from this image. We have prepared a docker image for the JETSCAPE environment, which allows you to use JETSCAPE on any operating system without installing a long list of pre-reqs or worrying about interference with software you already have installed.
To illustrate what this will look like, consider the following standard workflow. In a terminal on your machine (call it Terminal 1), you will clone JETSCAPE — this terminal is on your "host" machine — just a standard, typical terminal. In another terminal (call it Terminal 2), you will invoke a command that runs a pre-defined docker container. Terminal 2 then lives entirely inside this docker container, completely separated from your host machine. It can only access the files that are inside that pre-defined docker container — and not any of the files on your host machine — unless we explicitly share a folder between them. The standard workflow that we will use is the following: You will share the folder jetscape-docker between the host machine and the docker container. Then, anytime you want to build or run JETSCAPE, you must do it inside the docker container. But anytime you want to edit text files (e.g. to construct your own configuration file), you can do this from your host machine (which we recommend). Simple as that: Depending which action you want to do, perform it either on the host machine, or in the docker container, as appropriate — otherwise it will not work.
Install
macOS
- Install Docker Desktop for Mac: https://docs.docker.com/docker-for-mac/install/
- Open Docker, go to Preferences --> Resources and
- Set CPUs to one less than the max that your computer has (
sysctl -n hw.ncpu), - Set memory to what you are willing to give Docker (I use 12 out of 16 GB). It should always be a few GB less than the size of you memory.
- Set CPUs to one less than the max that your computer has (
linux
- Install Docker: https://docs.docker.com/install/
- Allow your user to run docker (requires admin privileges):
sudo groupadd docker
sudo usermod -aG docker $USER
- Log out and log back in.
For Windows, please follow the analogous instructions: https://docs.docker.com/install/
Please note that if you have an older OS, you may need to download an older version of docker.
Download the JETSCAPE docker container
The docker container will contain only the pre-requisite environment to build JETSCAPE, but will not actually contain JETSCAPE itself. Rather, we will share the directory from step (1) with the docker container. This will allow us to build and run JETSCAPE inside the docker container, but to easily edit macros and access the output files on our own machine.
Create and start the docker container that contains all of the JETSCAPE pre-reqs:
macOS:
docker run -it -v ~/jetscape-docker:/home/jetscape-user --name myJetscape jetscape/school:2023.1Linux:
docker run -it -v ~/jetscape-docker:/home/jetscape-user --name myJetscape --user $(id -u):$(id -g) jetscape/school:2023.1
Under Linux, if you encounter an error like permission denied, you can use sudo in front of the docker run command.
windows: For example open a Windows command window using the 'cmd' command then:
docker run -it -v <fullpath>/jetscape-docker:/home/jetscape-user --name myJetscape -p 8888:8888 jetscape/school:2023.1
where <fullpath> would be c:\users...\documents\ or wherever the jetscape-docker folder was placed.
For details on the compatibility of docker image versions with JETSCAPE 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/school:2023.1, 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 <limit>` 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 <container>` or `exit`
- To re-start the container: `docker start -ai <container>`
- To put a running container into detatched mode: `Ctrl-p Ctrl-q`, and to re-attach: `docker attach <container>`
- To delete a container: `docker container rm <container>`
After the docker is set up and we are inside the docker container, it looks like
jetscape-user@6d3daf01bb13:~$Some useful commands:
- To see the containers you have running, and get their ID:
docker container ls(-ato see also stopped containers) - To stop the container:
docker stop <container>orexit - To re-start the container:
docker start -ai <container> - To delete a container:
docker container rm <container>
Practice exiting and re-entering 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.
