From dd8e82384c3e0ff999d8f23cc3de4e4443fdd833 Mon Sep 17 00:00:00 2001 From: Marcello Stanisci Date: Thu, 1 Jun 2017 08:51:14 +0200 Subject: docs > doc, just to be consistent with other repos. --- doc/onboarding.texi | 410 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 410 insertions(+) create mode 100644 doc/onboarding.texi (limited to 'doc/onboarding.texi') 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-.sh}, in order to make +@code{test-} 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{/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. -- cgit v1.2.3