path: root/doc
diff options
authorPau Espin Pedrol <pespin@sysmocom.de>2020-03-11 17:49:42 +0100
committerpespin <pespin@sysmocom.de>2020-03-12 17:50:06 +0000
commitbff90dce73d82f7cf649d48680833e3e9dfdb8e7 (patch)
treeea179b6ee3fe6e004a6dd15438667dde5ccb777d /doc
parent7e0b2ddfb8f835f207758805e2dc4484e3633b2c (diff)
doc/manuals: Write proper content for Docker Setup section
Diffstat (limited to 'doc')
1 files changed, 52 insertions, 2 deletions
diff --git a/doc/manuals/chapters/docker.adoc b/doc/manuals/chapters/docker.adoc
index b7560e1..bc8ad00 100644
--- a/doc/manuals/chapters/docker.adoc
+++ b/doc/manuals/chapters/docker.adoc
@@ -1,6 +1,56 @@
== Docker Setup
-Available in osmocom's docker-playground.git subdirectory 'osmo-gsm-tester/'.
+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:
-//TODO: Explain more where to find, how to build, how to use.
+- 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
+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"