docker.md 4.38 KB
Newer Older
Andy Buckley's avatar
Andy Buckley committed
1
# Docker instructions
Christian Bierlich's avatar
Christian Bierlich committed
2 3 4

Obtaining docker is explained here: [https://docs.docker.com/engine/installation/.](https://docs.docker.com/engine/installation/)

Andy Buckley's avatar
Andy Buckley committed
5
## Linux prerequisites
Christian Bierlich's avatar
Christian Bierlich committed
6 7 8 9 10 11 12 13 14 15 16 17 18
*Note:* on Linux systems, make sure to create a group "docker"
and add yourself to it. Otherwise you will need to run all docker
commands as sudo.

```
sudo groupadd docker
sudo usermod -aG docker $USER
```

After that you need to `logout` and log back in for the group change to take effect. Now you are able to use docker without sudo.

These steps need only be done once.

Andy Buckley's avatar
Andy Buckley committed
19 20

## Mac prerequisites
Christian Bierlich's avatar
Christian Bierlich committed
21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38
Quote from docker webpage:
Docker for Mac requires OS X El Capitan 10.11 or newer macOS release running on a 2010 or newer Mac, with Intel’s hardware support for MMU virtualization. The app will run on 10.10.3 Yosemite, but with limited support. Please see What to know before you install for a full explanation and list of prerequisites.

Please use the docker webpage to obtain up--to--date information about possible Mac install issues.

### Obtaining a docker image for rivet

The command is simply:

```
docker pull hepstore/rivet:X.Y.Z
```

where X.Y.Z is the latest Rivet version. This will download and store the Docker container in /var/lib/docker on your Linux or Mac system.

For the rest of this document we will refer to the Rivet/image version number as "X.Y.Z": replace this with the Rivet version code that you are using, cf. the pull command above.


Andy Buckley's avatar
Andy Buckley committed
39
## Running the container interactively
Christian Bierlich's avatar
Christian Bierlich committed
40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57

The most basic thing to do is to simply run bash inside the container as such:


```
docker run -it --rm hepstore/rivet:X.Y.Z bash
```

This gives you full access to anything inside the container.
This is probably a good cross-check to see if your docker permissions
are correct.

To see a list of available rivet analysis you can now do this:

```
docker run -i --rm hepstore/rivet:X.Y.Z rivet --list-analyses
```

Andy Buckley's avatar
Andy Buckley committed
58 59 60

##  Running Rivet through docker

Christian Bierlich's avatar
Christian Bierlich committed
61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79
In the following, a proposed way of working with rivet through docker is given.

To mount your current directory on the host system into the container and making it the current directory inside the container as well and set the same user and group ids as on the host system, we add this to the command line:

```
 -v $PWD:$PWD -w $PWD -u `id -u $USER`:`id -g`
```


A very efficient way of using rivet through docker is to use aliases as the command line does get quite lengthy.

If you set the following aliases in your shell, you have everything set up to run rivet, compile your own analysis code and make plots:

```
alias rivet='docker run -i  --rm  -u `id -u $USER`:`id -g`  -v $PWD:$PWD -w $PWD  hepstore/rivet:X.Y.Z rivet'
alias rivet-mkanalysis='docker run -i  --rm  -u `id -u $USER`:`id -g`  -v $PWD:$PWD -w $PWD  hepstore/rivet:X.Y.Z rivet-mkanalysis'
alias rivet-buildplugin='docker run -i  --rm  -u `id -u $USER`:`id -g`  -v $PWD:$PWD -w $PWD  hepstore/rivet:X.Y.Z rivet-buildplugin'
alias rivet-mkhtml='docker run -i  --rm  -u `id -u $USER`:`id -g`  -v $PWD:$PWD -w $PWD  hepstore/rivet:X.Y.Z rivet-mkhtml'
alias yodamerge='docker run -i --rm  -u `id -u $USER`:`id -g`  -v $PWD:$PWD -w $PWD  hepstore/rivet:X.Y.Z yodamerge'
Andy Buckley's avatar
Andy Buckley committed
80
```
Christian Bierlich's avatar
Christian Bierlich committed
81 82 83 84 85 86 87

You might want to put these alias definitions into your `~/.bashrc` for persistence.

*Note:* on SELinux systems, an additional docker run flag `--privileged` is sometimes required for read/write permissions:
```
alias rivet='docker run -i --privileged --rm  -u `id -u $USER`:`id -g`  -v $PWD:$PWD -w $PWD  hepstore/rivet:X.Y.Z rivet'
alias rivet-mkanalysis='docker run -i --privileged --rm  -u `id -u $USER`:`id -g`  -v $PWD:$PWD -w $PWD  hepstore/rivet:X.Y.Z rivet-mkanalysis'
Christian Bierlich's avatar
Christian Bierlich committed
88
alias rivet-build='docker run -i --privileged --rm  -u `id -u $USER`:`id -g`  -v $PWD:$PWD -w $PWD  hepstore/rivet:X.Y.Z rivet-build'
Christian Bierlich's avatar
Christian Bierlich committed
89 90 91 92
alias rivet-mkhtml='docker run -i --privileged --rm  -u `id -u $USER`:`id -g`  -v $PWD:$PWD -w $PWD  hepstore/rivet:X.Y.Z rivet-mkhtml'
alias yodamerge='docker run -i --privileged --rm  -u `id -u $USER`:`id -g`  -v $PWD:$PWD -w $PWD  hepstore/rivet:X.Y.Z yodamerge'
```

Andy Buckley's avatar
Andy Buckley committed
93 94 95 96 97 98 99
You now can use the following commands from your host system's terminal:

* `rivet`              --- this is the main program
* `rivet-mkanalysis`   --- this creates analysis code templates
* `rivet-build`        --- this compiles your own analysis code
* `rivet-mkhtml`       --- this is used for plotting the output histograms

Christian Bierlich's avatar
Christian Bierlich committed
100
This should allow you to follow eg. the [firstrun.md](First run) tutorial on your host system.