[taler-docs] branch master updated: improve merchant manual

[gnunet]

This is an automated email from the git hooks/post-receive script.

grothoff pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new b1d2864  improve merchant manual
     new 91a6f97  Merge branch 'master' of git+ssh://git.taler.net/docs
b1d2864 is described below

commit b1d2864aa3c80a223a782352aa5fb64f4d613424
Author: Christian Grothoff <christian@grothoff.org>
AuthorDate: Thu Jun 25 22:54:04 2020 +0200

    improve merchant manual
---
 taler-merchant-manual.rst | 158 +++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 135 insertions(+), 23 deletions(-)

diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst
index f8515c0..d6f07ef 100644
--- a/taler-merchant-manual.rst
+++ b/taler-merchant-manual.rst
@@ -152,11 +152,13 @@ backend:
 
 -  libargon2 >= 20171227 (GNUnet 0.13 needs it to build, not actively used by 
GNU Taler)
 
+-  libsqlite3 >= 3.0 (GNUnet 0.13 needs it to build, not actively used by GNU 
Taler)
+
 -  libjansson >= 2.7
 
 -  Postgres >= 9.6, including libpq
 
--  libgnunetutil (from Git)
+-  GNUnet (from Git)
 
 -  GNU Taler exchange (from Git)
 
@@ -169,20 +171,20 @@ the libgnunetutil and GNU Taler exchange dependencies.
 
 .. _Installing-libgnunetutil:
 
-Installing libgnunetutil
-^^^^^^^^^^^^^^^^^^^^^^^^
+Installing GNUnet
+^^^^^^^^^^^^^^^^^
 
 .. index:: GNUnet
 
-Before you install libgnunetutil, you must download and install the
-dependencies mentioned in the previous section, otherwise the build may
-succeed but fail to export some of the tooling required by Taler.
+Before you install GNUnet, you must download and install the dependencies
+mentioned in the previous section, otherwise the build may succeed, but could
+fail to export some of the tooling required by GNU Taler.
 
-To download and install libgnunetutil, proceed as follows:
+To download and install GNUnet, proceed as follows:
 
 ::
 
-   $ git clone https://gnunet.org/git/gnunet/
+   $ git clone https://git.gnunet.org/gnunet/
    $ cd gnunet/
    $ ./bootstrap
    $ ./configure [--prefix=GNUNETPFX]
@@ -194,6 +196,11 @@ To download and install libgnunetutil, proceed as follows:
 If you did not specify a prefix, GNUnet will install to ``/usr/local``,
 which requires you to run the last step as ``root``.
 
+There is no need to actually run a GNUnet peer to use the Taler merchant
+backend -- all the merchant needs from GNUnet is a number of headers and
+libraries!
+
+
 .. _Installing-the-GNU-Taler-exchange:
 
 Installing the GNU Taler exchange
@@ -206,7 +213,7 @@ follows:
 
 ::
 
-   $ git clone git://taler.net/exchange
+   $ git clone https://git.taler.net/exchange/
    $ cd exchange
    $ ./bootstrap
    $ ./configure [--prefix=EXCHANGEPFX] \
@@ -216,10 +223,15 @@ follows:
    $ make
    # make install
 
-If you did not specify a prefix, the exchange will install to
-``/usr/local``, which requires you to run the last step as ``root``.
-Note that you have to specify ``--with-gnunet=/usr/local`` if you
-installed GNUnet to ``/usr/local`` in the previous step.
+If you did not specify a prefix, the exchange will install to ``/usr/local``,
+which requires you to run the last step as ``root``.  You have to specify
+``--with-gnunet=/usr/local`` if you installed GNUnet to ``/usr/local`` in the
+previous step.
+
+There is no need to actually run a Taler exchange to use the Taler merchant
+backend -- all the merchant needs from the Taler exchange is a few headers and
+libraries!
+
 
 .. _Installing-the-GNU-Taler-merchant-backend:
 
@@ -234,7 +246,7 @@ Use the following commands to download and install the 
merchant backend:
 
 ::
 
-   $ git clone git://taler.net/merchant
+   $ git clone https://git.taler.net/merchant/
    $ cd merchant
    $ ./bootstrap
    $ ./configure [--prefix=PFX] \
@@ -243,12 +255,24 @@ Use the following commands to download and install the 
merchant backend:
    $ # Each dependency can be fetched from non standard locations via
    $ # the '--with-<LIBNAME>' option. See './configure --help'.
    $ make
-   $ make install
+   # make install
+
+If you did not specify a prefix, the exchange will install to
+``/usr/local``, which requires you to run the last step as ``root``.
 
-Note that you have to specify ``--with-exchange=/usr/local`` and/or
+You have to specify ``--with-exchange=/usr/local`` and/or
 ``--with-exchange=/usr/local`` if you installed the exchange and/or
 GNUnet to ``/usr/local`` in the previous steps.
 
+Depending on the prefixes you specified for the installation and the
+distribution you are using, you may have to edit ``/etc/ld.so.conf``, adding
+lines for ``GNUNETPFX/lib/`` and ``EXCHANGEPFX/lib/`` and ``PFX/lib/``
+(replace the prefixes with the actual paths you used). Afterwards, you should
+run ``ldconfig``. Without this step, it is possible that the linker may not
+find the installed libraries and launching the Taler merchant backend would
+then fail.
+
+
 .. _Installing-Taler-on-Debian-GNU_002fLinux:
 
 Installing Taler on Debian GNU/Linux
@@ -381,6 +405,8 @@ To run the Taler backend on TCP port 8888, use:
       $ taler-config -s MERCHANT -o SERVE -V TCP
       $ taler-config -s MERCHANT -o PORT -V 8888
 
+
+
 Currency
 ^^^^^^^^
 
@@ -399,6 +425,7 @@ https://exchange.demo.taler.net/:
 
       $ taler-config -s TALER -o CURRENCY -V KUDOS
 
+
 Database
 ^^^^^^^^
 
@@ -429,7 +456,7 @@ run
 
    ::
 
-      $ sudu -u postgres createuser -d $USER
+      $ sudo -u postgres createuser -d $USER
 
 as the Postgres database administrator (usually ``postgres``) to
 grant ``$USER`` the ability to create new databases. Next, you should
@@ -449,6 +476,21 @@ To configure the Taler backend to use this database, run:
       $ taler-config -s MERCHANTDB-postgres -o CONFIG \
         -V postgres:///$DBNAME
 
+Now you should create the tables and indices. To do this, run as ``$USER``:
+
+   ::
+
+      $ taler-merchant-dbinit
+
+
+You can improve your security posture if you now REVOKE the rights to CREATE,
+DROP or ALTER tables from ``$USER``. However, if you do so, please be aware
+that you may have to temporarily GRANT those rights again when you update the
+merchant backend.  For details on how to REVOKE or GRANT these rights, consult
+the Postgres documentation.
+
+
+
 .. index: MASTER_KEY
 
 Exchange
@@ -592,15 +634,18 @@ Launching the backend
 .. index:: taler-merchant-httpd
 
 Assuming you have configured everything correctly, you can launch the
-merchant backend using:
+merchant backend as ``$USER`` using:
 
 ::
 
    $ taler-merchant-httpd
 
-When launched for the first time, this command will print a message
-about generating your private key. If everything worked as expected, the
-command
+To ensure the process runs always in the background and also after rebooting,
+you should use systemd, cron or some other init system of your operating
+system to launch the process. Consult the documentation of your operating
+system for how to start and stop daemons.
+
+If everything worked as expected, the command
 
 ::
 
@@ -614,7 +659,8 @@ should return the message
 
 Please note that your backend is right now likely globally reachable.
 Production systems should be configured to bind to a UNIX domain socket
-or properly restrict access to the port.
+and use TLS for improved network privacy, see `Secure setup <#Secure-setup>`__.
+
 
 .. _Instances:
 
@@ -632,6 +678,8 @@ backend (possibly via a Web interface -- once we implement 
that).
 FIXME: more details on how to setup instances here!
 
 
+
+
 Accounts
 --------
 
@@ -647,10 +695,74 @@ a ``payto://``-URL.
 FIXME: more details on how to setup accounts here!
 
 
+Upgrade procedure
+=================
+
+This is the general upgrade procedure.  Please see the release notes
+for your specific version to check if a particular release has special
+upgrade requirements.
+
+Please note that upgrades are ONLY supported for released version of the
+merchant. Attempting to upgrade from or to a version in Git is not supported
+and may result in subtle data loss.
+
+To safely upgrade the merchant, you should first stop the existing
+taler-merchant-httpd process, backup your merchant database (see Postgres
+manual), and then install the latest version of the code.
+
+If you REVOKED database permissions, ensure that the rights to CREATE,
+DROP, and ALTER tables are GRANTed to ``$USER`` again.  Then, run:
+
+     ::
+
+         $ taler-merchant-dbinit
+
+to upgrade the database to the latest schema.  After that, you may again
+REVOKE the database permissions. Finally, restart the HTTP service, either via
+your systemd or init system, or directly using:
+
+     ::
+
+         $ taler-merchant-httpd
+
+
 
 Advanced topics
 ===============
 
+.. _Secure-setup:
+
+Secure setup
+------------
+
+.. index:: security
+.. index:: TLS
+
+For additional security, you may want to have the backend bind to a UNIX
+domain socket and use an HTTP reverse proxy for TLS termination:
+
+   ::
+
+      $ taler-config -s MERCHANT -o SERVE -V UNIX
+      $ taler-config -s MERCHANT -o UNIXPATH -V /some/path/here.sock
+
+Assuming your domain name is /example.com/ and you have TLS configured,
+a possible reverse proxy directive for Nginx would be:
+
+   ::
+
+      proxy_pass http://unix:/some/path/here.sock;
+      proxy_redirect off;
+      proxy_set_header Host $host;
+      proxy_set_header X-Forwarded-Host "example.com";
+      proxy_set_header X-Forwarded-Proto "https";
+
+Leave out the last line if your Nginx reverse proxy does not have HTTPS
+enabled.  Make sure to restart the /taler-merchant-httpd/ process after
+changing the configuration.
+
+
+
 Configuration format
 --------------------
 
@@ -726,7 +838,7 @@ configuration file used in our demos. See under 
``deployment/config``.
 .. _Using-taler_002dconfig:
 
 Using taler-config
-------------------
+^^^^^^^^^^^^^^^^^^
 
 .. index:: taler-config
 

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.