From: Hades DAQ Date: Sun, 3 Mar 2019 20:29:18 +0000 (+0100) Subject: fixed another date typo. Also added detailed README.txt X-Git-Url: https://jspc29.x-matter.uni-frankfurt.de/git/?a=commitdiff_plain;h=fbcd6f1641eb6fb2ba5c1fc0fc991f11244592f7;p=dockerfiles.git fixed another date typo. Also added detailed README.txt --- diff --git a/go4_trbnet/README.txt b/go4_trbnet/README.txt new file mode 100644 index 0000000..a8de433 --- /dev/null +++ b/go4_trbnet/README.txt @@ -0,0 +1,230 @@ +################################################## +## Introduction ## +################################################## + + + +## The idea: ## + +I want to: + + - install all necessary software to run + a TRB3 data acquisition system all in one go. + +By necessary software I mean: + + - root6 + dabc + stream + go4 + - trbnettools + - daqtools + - all libraries/packages required to run the above + +Furthermore: + + - All components should compile without problems + - All components should be compatible to each other + - I want to start with a stable system + - I want to make changes/updates + - I want to revert changes if they break my running system + + +## The solution: ## + +We put all software components in a docker container. + + +################################################## +## Docker in a nutshell ## +################################################## + + +What is a docker container? + + - It is sort of a virtual machine ... but not really. + - It is a sealed "sandbox", i.e. a virtual container where + "guest software" is separated from the host system. + - The container includes its own minimal linux distribution + - There are no software dependencies between the software + in the container and the host system. + - However, the container uses the kernel of the host system, + (so it is rather an elaborate chroot environment than a + virtual machine) + - Performance of the software in the container is comparable + to natively running processes on the host system. + - Two or more containers can be started at the same time + - An entire container can be dumped to a single file and can + be started on another host + - Containers can be conveniently shared via the docker cloud + (which is a free service) + - All described functionality is provided/managed by the docker daemon + + +How are such containers created/managed? + + - A container is compiled from a so-called Dockerfile + - A Dockerfile is similar to a shell script, + i.e. it contains commands which are executed line by line. + - It starts with a "FROM" statement which tells docker which + base system to start from (e.g. a minimal ubuntu/opensuse/fedora + distribution, in our opensuse leap 15.0). + The base image is pulled from the docker cloud. + - The ensuing RUN statements are executed already inside the + new container. They can be used to execute any command + known to the system in the container, e.g. to install + system packages with the package manager, download + source packages, compile and install software + - During container build time, if a RUN statement executes + successfully (exit 0), + then a new "layer" is added to the binary image of the + container. Otherwise the compilation process breaks. + - A Dockerfile can be extended. When compiled again, + already successfully processed RUN statements are skipped + (as the resulting binary layers already exist) + - If RUN statements are removed at the end of the Dockerfile, + the container returns to an earlier state. This takes practically + no time, as docker simply removes some binary layers from + the image. + - Think of a docker container as a "binary SVN" of a + small linux distro. + - As a by-product of setting up your container, + you get a fool-prof/tested/certified + step-by-step compilation/installation manual (the Dockerfile) + for the software collection running in the container. + This might be useful to have, even if you decide to install + your software natively, without using a container. + + +Typical use: + - A container is started and stopped like an application, + and not like a virtual machine. + - Once the Dockerfile is completely compiled, the container + can be started again and again in a matter of seconds. + - When its job is done, the container is destroyed again. + - On destruction, the container forgets everything that + happened while it was running. On the next start, it starts + exactly in the last state defined by the Dockerfile. + + +How can I get files in and out of my container? + - Host system directories can be easily mounted inside the + container. (docker run -v /host/dir/:/container/dir/) + - Those directories can be read and written from host and + container side. + + +################################################## +## get Docker ## +################################################## + + + +-- step 1 -- +install docker with your package manager + +(ubuntu/debian) $ sudo apt-get install docker +(opensuse) $ sudo zypper install docker + +-- step 2 -- +add your user to the docker group: +$ sudo usermod -a -G docker + +(you might need to log out and back in for the changes +to become effective) + +-- step 3 -- +start docker daemon: +$ sudo service docker start + + + +################################################## +## get/start go4_trbnet ## +################################################## + + +-- step 1 -- +get the go4_trbnet dockerfiles +$ git clone git@jspc29.x-matter.uni-frankfurt.de:dockerfiles +$ cd go4_trbnet + +when you read this README, you have already done this step + + +-- step 2 -- +Now you have two options: + + - Option 1: Start with a minimal opensuse leap 15.0, compile all TRB3 software from sources: + $ cd go4_trbnet_leap_15.0_stable_2019-03-01 + + - Option 2: Start with a completely prebuilt container from the cloud. Speeds up things ... + $ cd go4_trbnet_leap_15.0_stable_2018-03-01_prebuilt + + +-- step 3 -- + +In this directory you find: + + - the Dockerfile (go ahead, look inside, it is not scary) + + - two directories "conf/" and "workdir/". Both directories will be + mounted in the container. Those directories wil NOT be reset + when the container is stopped. + + - conf/ + contains conf.sh (and some other shell scripts and config files) + to set environment variables + (e.g. DAQOPSERVER, TRB3_SERVER ... ), + and to start (or not start) certain services: + - trbnetd + - CTS gui backend + DAQ control webserver + - vncserver (for Go4 and other graphical applications) + - dhcp server for + (look at conf.sh it is pretty straightforward, adapt to your needs) + + - workdir/ + ... this will be your workdir ... + it contains an example start.sh, + which starts a tmux session and in it some applications (dabc, go4, a browser). + (look at start.sh it is pretty straightforward, adapt to your needs) + + +-- step 4 -- +Build and run your container: + +$ ./build_and_run.sh + +enjoy! When everything compiled and started correctly, you will be presented with +a tmux session displaying an info text about the started services +and a list of the most important tmux hotkeys to navigate your session. + +If enabled in conf.sh, a vnc server is started on port 5902 hosting a firefox window +displaying the DAQ Control overview website. (connect with vncviewer localhost:5902) + + +-- step 5 -- +You want additional system packages or other software in my container? +You want to update to the latest versions of trbnettools/daqtools/go4 ? + +no problem. + +Look at your Dockerfile. At the end, there are some commented out codeblocks, +showing you how to install additional software or update TRB3-related +software. + +Go ahead, extend your Dockerfile. You cannot break anything. +If you delete/comment out changes again, the container will revert exactly +to its previous state. + + +If you don't like my init script stuff, simply remove it and have it your own way. + + + +################################################## +## about / contact ## +################################################## +## ## +## Michael Wiebusch 2019-03-03 ## +## antiquark@gmx.net ## +## ## +################################################## + diff --git a/go4_trbnet/go4_trbnet_leap_15.0_stable_2019-03-01_prebuilt/Dockerfile b/go4_trbnet/go4_trbnet_leap_15.0_stable_2019-03-01_prebuilt/Dockerfile index b30a064..73860ba 100644 --- a/go4_trbnet/go4_trbnet_leap_15.0_stable_2019-03-01_prebuilt/Dockerfile +++ b/go4_trbnet/go4_trbnet_leap_15.0_stable_2019-03-01_prebuilt/Dockerfile @@ -2,7 +2,7 @@ ## get prebuilt image from docker cloud ## ################################################## -FROM acidbourbon/go4_trbnet_leap_15.0:stable_2018-03-01 +FROM acidbourbon/go4_trbnet_leap_15.0:stable_2019-03-01 # see prebuilt_Dockerfile for "content" of prebuilt image