From b1d2864aa3c80a223a782352aa5fb64f4d613424 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Thu, 25 Jun 2020 22:54:04 +0200 Subject: improve merchant manual --- taler-merchant-manual.rst | 158 +++++++++++++++++++++++++++++++++++++++------- 1 file changed, 135 insertions(+), 23 deletions(-) (limited to 'taler-merchant-manual.rst') diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst index f8515c0a..d6f07efb 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-' 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 -- cgit v1.2.3