doc/manuals/chapters/docker.adoc

[[docker]]
== Docker Setup

A sample {app-name} setup based on docker containers and maintained by the
Osmocom community is available in Osmocom's git repository
link:https://git.osmocom.org/docker-playground/[docker-playground.git], under
'osmo-gsm-tester' subdirectory. In there, one can find:

- A 'Dockerfile' file can be found which builds a docker image which can
be used both to run as an osmo-gsm-tester <<install_main_unit,Main Unit>> or as
a <<install_slave_unit,Slave Unit>>. The main difference to use it as one or the
other is whether osmo-gsm-tester.py is run on it (Main Unit) or otherwise sshd
(Slave Unit). A convenience script is provided in the same directory to start
the processes just explained ('osmo-gsm-tester-{master,slave}.sh').

- A 'jenkins.sh' file is provided which handles all the
magic to start a Main Unit and a Slave Unit on the same docker private network
so they can interact. It also takes care on running the docker containers with
all the required permissions, mount all virtual filesystem bindings, etc.

- A sample <<resources_conf,resources.conf>> file is provided which
provides some virtual resources configured to be run on the Slave Unit.

The 'jenkins.sh' script expects the <<trials, trial directory>> to be in
'/tmp/trial', and will bind that directory to the docker Main Unit instance so
osmo-gsm-tester uses it. Hence, one must place a the trial to be run in there
before running the setup. There is yet no specific docker container available to
build trials, but one can re-use an Osmocom jenkins slave container available to
in 'docker-playground.git' in order to build them using the scripts in
'osmo-gsm-tester.git/contrib/jenkins-build-*.sh'. Alternatively, the quick way
is to get them from any of the Osmocom's {app-name}
link:https://jenkins.osmocom.org/jenkins/view/osmo-gsm-tester/[jenkins jobs],
which store them as artifacts.

When running the whole setup through the 'jenkins.sh' script, standard out
('stdout') and standard error ('stderr') outputs for each docker container are
made available to the host running the script, under '/tmp/logs' directory.
Results generated by {app-name}'s last run can be found as usual under the trial
directory ('/tmp/trial/last_run').

The {app-name} git revision being checked out to build and run inside the
docker containers can be selected by setting the 'OSMO_GSM_TESTER_BRANCH'
environment variable. For instance, to install and run branch 'mybranch' in
'osmo-gsm-tester.git', one can use:
----
export OSMO_GSM_TESTER_BRANCH=mybranch
./jenkins.sh
----

Specific command line parameters to be passed to {app-name} process inside the
Main Unit docker container instance can be set with the 'OSMO_GSM_TESTER_OPTS'
environment variable. For instance, to run suite '4g' with debug logging level:
----
export OSMO_GSM_TESTER_OPTS="-s 4g -l dbg"
./jenkins.sh
----