summaryrefslogtreecommitdiff
path: root/taler-merchant-manual.rst
diff options
context:
space:
mode:
authorChristian Grothoff <christian@grothoff.org>2020-06-25 22:54:04 +0200
committerChristian Grothoff <christian@grothoff.org>2020-06-25 22:54:04 +0200
commitb1d2864aa3c80a223a782352aa5fb64f4d613424 (patch)
tree9766ceead3819a26fb5f9bbd2ba02ae352add356 /taler-merchant-manual.rst
parentcd10263cc144e7a3987f70b7b02d7c980a87b058 (diff)
downloaddocs-b1d2864aa3c80a223a782352aa5fb64f4d613424.tar.gz
docs-b1d2864aa3c80a223a782352aa5fb64f4d613424.tar.bz2
docs-b1d2864aa3c80a223a782352aa5fb64f4d613424.zip
improve merchant manual
Diffstat (limited to 'taler-merchant-manual.rst')
-rw-r--r--taler-merchant-manual.rst158
1 files changed, 135 insertions, 23 deletions
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-<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