summaryrefslogtreecommitdiff
path: root/doc/onboarding.texi
diff options
context:
space:
mode:
Diffstat (limited to 'doc/onboarding.texi')
-rw-r--r--doc/onboarding.texi410
1 files changed, 410 insertions, 0 deletions
diff --git a/doc/onboarding.texi b/doc/onboarding.texi
new file mode 100644
index 0000000..3327b2a
--- /dev/null
+++ b/doc/onboarding.texi
@@ -0,0 +1,410 @@
+@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
+
+
+This tecnique aims to set a thorough Taler installation up on a
+machine whose nginx configuration is configured by config files
+from @indicateurl{https://git.taler.net/deployment.git/tree/etc/nginx}.
+
+This installation assumes that all the steps are run with @code{$HOME}
+as @code{$CWD}.
+
+The first step is to fetch the @cite{deployment} repository, which hosts all
+the needed scripts.
+
+@example
+# Adapt the repository's URI to your needs.
+$ git clone /var/git/deployment.git/
+@end example
+
+The next step is to fetch all the codebases from all the components.
+
+@example
+$ ./deployment/bootstrap-standalone
+@end example
+
+If the previous step succeeded, a file named @code{activate} should be now
+in the @code{$CWD}. It contains environmental definitions for @code{$PATH} and
+database names.
+
+@cartouche
+@quotation Note
+Please @emph{ignore} the output from the previous script when it succeeds,
+which is
+
+@quotation
+
+@example
+WARNING: enabling "trust" authentication for local connections
+You can change this by editing pg_hba.conf or using the option -A, or
+--auth-local and --auth-host, the next time you run initdb.
+
+Success. You can now start the database server using:
+
+/usr/lib/postgresql/9.5/bin/pg_ctl -D talerdb -l logfile start
+@end example
+
+The reason is that this message is generated by Postgresql's utilities and
+you never need to start your database manually; it will be started by the
+init script that launches all the Taler processes.
+@end quotation
+@end quotation
+@end cartouche
+
+Now we need to compile and install all the downloaded codebases.
+
+@example
+# We first update `@w{`}$PATH`@w{`}, in order to make all the compilation
+# and configuration utilities available.
+$ source activate
+
+# Double check if the previous step worked: $PATH should
+# contain $HOME/local/bin.
+$ echo $PATH
+
+# The actual compilation:
+$ taler-deployment-build
+@end example
+
+The following step will generate config files for all the components.
+Please @strong{note} that although a default currency will be picked up by the
+script, it is possible to have a custom currency by setting the environment
+variable @code{TALER_CONFIG_CURRENCY} to the wanted currency, and then running
+the config generator.
+
+@example
+$ taler-deployment-config-generate
+@end example
+
+whereas the following one will place signatures inside wireformat JSON
+files.
+
+@example
+$ taler-deployment-config-sign
+@end example
+
+The next step is to generate @cite{signkeys} and @cite{denomkeys}.
+Note that it will also get the denomkeys signed by the (local mock)
+auditor.
+
+@example
+$ taler-deployment-keyup
+@end example
+
+@c An error of "invalid currency name" might be related to the current
+@c policy of 12-chars limit for currency names; which is likely going to
+@c be changed.
+
+It may be necessary to define database tables for the exchange. The
+following command does that.
+
+Note that you have to manually start the database, with the following
+command.
+
+@example
+taler-deployment-arm -s
+taler-deployment-arm -i taler-postrges-standalone
+@end example
+
+@example
+# Erase all the data!
+$ taler-exchange-dbinit -r
+@end example
+
+As of the merchant backend, it creates tables at launch time, so it is
+not required to define tables before launching it. @cite{However}, if some
+table's definition changed over the time, and there is a need to force
+a redefinition of tables, then the following command accomplishes that
+for the merchant:
+
+@example
+# Erase all the data!
+$ taler-merchant-dbinit -r
+@end example
+
+If all previous steps succeeded, it is now possible to launch all the
+processes. That is accomplished by the following command:
+
+@example
+$ taler-deployment-start
+@end example
+
+@cartouche
+@quotation Note
+Please make sure your nginx works correctly with its configuration
+at @code{<DEPLOYMENT-REPO>/etc/nginx}.
+@end quotation
+@end cartouche
+
+@node Deployment on demo.taler.net
+@section Deployment on demo.taler.net
+
+This section describes how to upgrade the exchange deployment on the
+@url{taler.net} Web site. Here, the deployment scripts include a
+``stable'' setup at @url{demo.taler.net} and an ``experimental'' setup
+at @url{test.taler.net}. This section documents the steps for moving
+the ``experimental'' logic to the ``stable'' site. It is mostly
+useful for administrators of @url{taler.net}, but given that all of
+the configuration files are public, it may also make a good starting
+point for others.
+
+
+First, make sure that the deployment @emph{AND} the deployment scripts work on the @cite{test.taler.net} deployment.
+
+For all repositories that have a separate stable branch (currently exchange.git,
+merchant.git, merchant-frontends.git, bank.git, landing.git) do:
+
+@example
+$ cd $REPO
+$ git pull origin master stable
+$ git checkout stable
+
+# option a: resolve conflicts resulting from hotfixes
+$ git merge master
+$ ...
+
+# option b: force stable to master
+$ git update-ref refs/heads/stable master
+
+$ git push # possibly with --force
+
+# continue development
+$ git checkout master
+@end example
+
+Log into taler.net with the account that is @emph{not} active by looking
+at the @cite{sockets} symlink of the @cite{demo} account.
+
+The following instructions wipe out the old deployment completely.
+
+@example
+$ ls -l ~demo/sockets
+
+[...] sockets -> /home/demo-green/sockets/
+@end example
+
+In this case, @cite{demo-green} is the active deployment, and @cite{demo-blue} should be updated.
+After the update is over, the @cite{/home/demo/sockets} symlink will be pointed to @cite{demo-blue}.
+
+@example
+# Remove all existing files
+$ find $HOME -exec rm -fr @{@} \;
+
+$ git clone /var/git/deployment.git
+$ ./deployment/bootstrap-bluegreen demo
+
+# set environment appropriately
+$ . activate
+$ taler-deployment-build
+
+# upgrade the database! this
+# process depends on the specific version
+
+$ taler-deployment-start
+
+# look at the logs, verify that everything is okay
+@end example
+
+Now the symlink can be updated.
+
+@node releases
+@section releases
+
+
+@subsection Release Process and Checklists
+
+This document describes the process for releasing a new version of the various
+Taler components to the official GNU mirrors.
+
+The following components are published on the GNU mirrors
+
+@itemize
+@item taler-exchange (exchange.git)
+@item taler-merchant (merchant.git)
+@item talerfrontends (merchant-frontends.git)
+@item taler-bank (bank.git)
+@item taler-wallet-webex (wallet-webex.git)
+@end itemize
+
+@subsection Tagging
+
+Tag releases with an @b{annotated} commit, like
+
+@example
+git tag -a v0.1.0 -m "Official release v0.1.0"
+git push origin v0.1.0
+@end example
+
+@subsection Database for tests
+
+For tests in the exchange and merchant to run, make sure that
+a database @emph{talertest} is accessible by @emph{$USER}. Otherwise tests
+involving the database logic are skipped.
+
+@subsection Exchange, merchant
+
+Set the version in @code{configure.ac}. The commit being tagged
+should be the change of the version.
+
+For the exchange test cases to pass, @code{make install} must be run first.
+Without it, test cases will fail because plugins can't be located.
+
+
+@example
+./bootstrap
+./configure # add required options for your system
+make dist
+tar -xf taler-$COMPONENT-$VERSION.tar.gz
+cd taler-$COMPONENT-$VERSION
+make install check
+@end example
+
+
+@subsection Wallet WebExtension
+
+The version of the wallet is in @emph{manifest.json}. The @code{version_name} should be
+adjusted, and @emph{version} should be increased independently on every upload to
+the WebStore.
+
+@example
+./configure
+make dist
+@end example
+
+@c FIXME: selenium test cases
+
+
+@subsection Upload to GNU mirrors
+
+See @emph{https://www.gnu.org/prep/maintain/maintain.html#Automated-FTP-Uploads}
+
+Directive file:
+
+@example
+version: 1.2
+directory: taler
+filename: taler-exchange-0.1.0.tar.gz
+@end example
+
+Upload the files in @b{binary mode} to the ftp servers.