diff options
author | Marcello Stanisci <marcello.stanisci@inria.fr> | 2017-05-31 10:11:32 +0200 |
---|---|---|
committer | Marcello Stanisci <marcello.stanisci@inria.fr> | 2017-05-31 10:12:09 +0200 |
commit | 1cf8f0b1c860356443017fb23c3d655a4d7c7d4e (patch) | |
tree | 3b6481ac9b5b02d68dcb50ccd6699f760b3e4ccb /docs | |
parent | dbe476150be19b74f837de13c406a42f80b3e251 (diff) | |
download | deployment-1cf8f0b1c860356443017fb23c3d655a4d7c7d4e.tar.gz deployment-1cf8f0b1c860356443017fb23c3d655a4d7c7d4e.tar.bz2 deployment-1cf8f0b1c860356443017fb23c3d655a4d7c7d4e.zip |
starting "onboarding" documentation
Diffstat (limited to 'docs')
-rw-r--r-- | docs/onboarding.texi | 208 |
1 files changed, 208 insertions, 0 deletions
diff --git a/docs/onboarding.texi b/docs/onboarding.texi new file mode 100644 index 0000000..7b9ccce --- /dev/null +++ b/docs/onboarding.texi @@ -0,0 +1,208 @@ +@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. |