docker.md 4.46 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
88
89
90
91
92

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'
alias rivet-buildplugin='docker run -i --privileged --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 --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

Saad Patel's avatar
Saad Patel committed
100
This should allow you to follow eg. the [firstrun.md](https://gitlab.com/hepcedar/rivet/-/blob/release-3-1-x/doc/tutorials/firstrun.md) tutorial on your host system.