--- /dev/null
+##################################################
+## 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 <username>
+
+(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 ##
+## ##
+##################################################
+
jspc29 / dockerfiles.git / commitdiff