From 1de5dad0d7da36af9152eaf5b9dbef73910c79a9 Mon Sep 17 00:00:00 2001
From: Marcello Stanisci <marcello.stanisci@inria.fr>
Date: Wed, 31 May 2017 15:53:27 +0200
Subject: texi-fying buildbot instructions

---
 docs/onboarding.texi | 121 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 121 insertions(+)

diff --git a/docs/onboarding.texi b/docs/onboarding.texi
index 64fb0b1..3327b2a 100644
--- a/docs/onboarding.texi
+++ b/docs/onboarding.texi
@@ -1,3 +1,124 @@
+@node Taler.net
+@section Taler.net
+
+This section documents the set-up of our main server @code{taler.net}.
+
+@subsection Buildbot
+
+@quotation Note
+'worker' and 'slave' are used interchangeably
+@end quotation
+
+The user running the buildbot master is @emph{containers}.
+
+@subsubsection Master
+
+To start the master, log in as @emph{containers}, and run:
+
+@example
+$ ~/buildbot/start.sh
+
+# To stop it, run:
+$ ~/buildbot/stop.sh
+@end example
+
+There is also a "restart" script, runnable as follows:
+
+
+@example
+$ ~/buildbot/restart.sh
+@end example
+
+@subsubsection Selenium worker
+
+This worker is responsible for running the Selenium wallet test:
+an automatic clicker that performs the cycle withdraw-and-spend.
+
+The @emph{containers} user is also responsible for running the Selenium
+buildbot worker.
+
+Start it with:
+
+@example
+$ source ~/buildbot/venv/bin/activate
+$ buildbot-worker start ~/buildbot/selenium_worker/
+
+# stop it with:
+$ buildbot-worker stop ~/buildbot/selenium_worker/
+
+# deactivate the virtual env with
+$ deactivate
+@end example
+
+@subsubsection Lcov worker
+
+The worker is implemented by the @emph{lcovslave} user and is responsible
+for generating the HTML showing the coverage of our tests, then available
+on @emph{https://lcov.taler.net}.
+
+To start the worker, log in as @emph{lcovslave} and run:
+
+@example
+$ source ~/activate
+$ taler-deployment-bbstart
+
+# To stop it:
+$ taler-deployment-bbstop
+@end example
+
+
+@subsubsection Switcher worker
+
+Taler.net uses a "blue/green" fashion to update the code it
+uses in demos.  Practically, there are two users: @emph{test-green}
+and @emph{test-blue}, and only one of them is "active" at any time.
+
+Being @emph{active} means that whenever nginx receives a HTTP request
+for one of the Taler services (at our demo), it routes the request
+to either test-blue or test-green via unix domain sockets.
+
+Upon any push to any of the Taler's subprojects, this worker is
+responsible for building the code hosted at the inactive user and,
+if all tests succeed, switching the active user to the one whose code
+has just been compiled and tested.
+
+The worker is implemented by the @emph{testswitcher} user. This user
+has some additional "sudo" rights, since it has to act as @emph{test-blue},
+`test-gree@emph{$1}est` user in order to accompish its task.
+Note that the "sudo file" is tracked in this (@emph{deployment}) repository,
+under the @emph{sudoers} directory.
+
+To start the worker, log in as @emph{testswitcher} and run:
+
+@example
+$ source ~/venv/bin/activate
+$ buildbot-worker start ~/buildbot/slave
+
+# To stop it:
+$ buildbot-worker stop ~/buildbot/slave
+
+# To exit the virtual env
+$ deactivate
+@end example
+
+@subsubsection Manual switch
+
+After the desired blue/green party has been compiled, it is possible to
+log-in as @emph{test} and run the script @code{$HOME/.ln-<COLOR>.sh}, in order to make
+@code{test-<COLOR>} active.
+
+-------------------
+Site lcov.taler.net
+-------------------
+
+The directory @code{/var/www/lcov.taler.net} contains the following two symlinks
+
+* exchange --> @code{/home/lcovslave/exchange/doc/coverage}
+* merchant --> @code{/home/lcovslave/merchant/doc/coverage}
+
+The pointed locations are updated by the @emph{lcovslave}.
+
+
 @node Standalone deployment
 @section Standalone deployment
 
-- 
cgit v1.2.3