Change in osmo-gsm-tester[master]: doc/manuals: Write proper content for Docker Setup section

[pespin]

pespin has uploaded this change for review. ( https://gerrit.osmocom.org/c/osmo-gsm-tester/+/17464 )


Change subject: doc/manuals: Write proper content for Docker Setup section
......................................................................

doc/manuals: Write proper content for Docker Setup section

Change-Id: Ie883adbf03a3b5c9a852182c01d15a212749ce04
---
M doc/manuals/chapters/docker.adoc
1 file changed, 52 insertions(+), 2 deletions(-)



  git pull ssh://gerrit.osmocom.org:29418/osmo-gsm-tester refs/changes/64/17464/1

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]]
 == 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
+./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
+----

-- 
To view, visit https://gerrit.osmocom.org/c/osmo-gsm-tester/+/17464
To unsubscribe, or for help writing mail filters, visit https://gerrit.osmocom.org/settings

Gerrit-Project: osmo-gsm-tester
Gerrit-Branch: master
Gerrit-Change-Id: Ie883adbf03a3b5c9a852182c01d15a212749ce04
Gerrit-Change-Number: 17464
Gerrit-PatchSet: 1
Gerrit-Owner: pespin <pespin at sysmocom.de>
Gerrit-MessageType: newchange
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osmocom.org/pipermail/gerrit-log/attachments/20200311/3b93b510/attachment.htm>