summaryrefslogtreecommitdiff
path: root/taler-merchant-manual.rst
diff options
context:
space:
mode:
authorChristian Grothoff <christian@grothoff.org>2020-12-05 19:47:03 +0100
committerChristian Grothoff <christian@grothoff.org>2020-12-05 19:47:03 +0100
commit6da702cb839b682d80d87fdcd88eb9ff16c189ae (patch)
tree24ef34da4c1c8f6da4ac782961479ad9bf422f0a /taler-merchant-manual.rst
parentdf9eb5452325255dfa77030eb539d0b8c88a6c9e (diff)
parent085d99420a7aa23b04bd4ce1e256eec9e182c166 (diff)
downloaddocs-6da702cb839b682d80d87fdcd88eb9ff16c189ae.tar.gz
docs-6da702cb839b682d80d87fdcd88eb9ff16c189ae.tar.bz2
docs-6da702cb839b682d80d87fdcd88eb9ff16c189ae.zip
Merge branch 'master' of git+ssh://git.taler.net/docs
Diffstat (limited to 'taler-merchant-manual.rst')
-rw-r--r--taler-merchant-manual.rst251
1 files changed, 121 insertions, 130 deletions
diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst
index a49b916..bff0e84 100644
--- a/taler-merchant-manual.rst
+++ b/taler-merchant-manual.rst
@@ -283,16 +283,6 @@ Installation of dependencies
The following packages need to be installed before we can compile the
backend:
-- autoconf >= 2.69
-
-- automake >= 1.14
-
-- libtool >= 2.4
-
-- autopoint >= 0.19
-
-- libltdl >= 2.4
-
- libunistring >= 0.9.3
- libcurl >= 7.26 (or libgnurl >= 7.26)
@@ -313,17 +303,26 @@ backend:
- GNU libmicrohttpd >= 0.9.71
-- GNUnet >= 0.14.0
+- GNUnet >= 0.14.0 (from `source tarball <http://ftpmirror.gnu.org/gnunet/>`__)
-- GNU Taler exchange (from Git or see `release announcement <https://mail.gnu.org/archive/cgi-bin/namazu.cgi?query=taler&idxname=info-gnu&max=20&result=normal&sort=date:late>`__)
+- GNU Taler exchange (see `release announcement <https://mail.gnu.org/archive/cgi-bin/namazu.cgi?query=taler&idxname=info-gnu&max=20&result=normal&sort=date:late>`__)
Except for the last two, these are available in most GNU/Linux distributions
and should just be installed using the respective package manager. Be careful
with GNU libmicrohttpd; here, some distributions only include an older version
that will not work.
+While you are in the GNU Taler exchange
+`download directory <http://ftpmirror.gnu.org/taler/>`__,
+you might as well also download the tarball for GNU Taler merchant.
+
+GNU Taler components version numbers follow the ``MAJOR.MINOR.MICRO`` format.
+The general rule for compatibility is that ``MAJOR`` and ``MINOR`` must match.
+Exceptions to this general rule are documented in the release notes.
+For example, Taler merchant 0.8.0 is compatible with Taler exchange 0.8.1.
+
The following sections will provide detailed instructions for installing
-the libgnunetutil and GNU Taler exchange dependencies.
+the ``libgnunetutil`` and GNU Taler exchange dependencies.
.. _Installing-libgnunetutil:
@@ -336,13 +335,11 @@ 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 GNUnet, proceed as follows:
+To download and install GNUnet, unpack the tarball and change
+into the resulting directory, then proceed as follows:
-::
+.. code-block:: console
- $ git clone https://git.gnunet.org/gnunet/
- $ cd gnunet/
- $ ./bootstrap
$ ./configure [--prefix=GNUNETPFX]
$ # Each dependency can be fetched from non standard locations via
$ # the '--with-<LIBNAME>' option. See './configure --help'.
@@ -364,20 +361,17 @@ Installing the GNU Taler exchange
.. index:: exchange
-After installing GNUnet, you can download and install the exchange as
-follows:
+After installing GNUnet, unpack the GNU Taler exchange tarball,
+change into the resulting directory, and proceed as follows:
- ::
+.. code-block:: console
- $ git clone https://git.taler.net/exchange.git/
- $ cd exchange
- $ ./bootstrap
- $ ./configure [--prefix=EXCHANGEPFX] \
- [--with-gnunet=GNUNETPFX]
- $ # Each dependency can be fetched from non standard locations via
- $ # the '--with-<LIBNAME>' option. See './configure --help'.
- $ make
- # make install
+ $ ./configure [--prefix=EXCHANGEPFX] \
+ [--with-gnunet=GNUNETPFX]
+ $ # Each dependency can be fetched from non standard locations via
+ $ # the '--with-<LIBNAME>' option. See './configure --help'.
+ $ 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``. You have to specify
@@ -398,13 +392,12 @@ Installing the GNU Taler merchant backend
The following steps assume all dependencies are installed.
-Use the following commands to download and install the merchant backend:
+First, unpack the GNU Taler merchant tarball and change into
+the resulting directory.
+Then, use the following commands to build and install the merchant backend:
- ::
+.. code-block:: console
- $ git clone https://git.taler.net/merchant/
- $ cd merchant
- $ ./bootstrap
$ ./configure [--prefix=PFX] \
[--with-gnunet=GNUNETPFX] \
[--with-exchange=EXCHANGEPFX]
@@ -435,30 +428,29 @@ Installing Taler on Debian GNU/Linux
------------------------------------
.. index:: Wheezy
+.. index:: Jessie
+.. index:: Stretch
.. index:: Debian
Debian wheezy is too old and lacks most of the packages required.
+Debian jessie is better, but still lacks PostgreSQL 9.6.
-On Debian jessie, only GNU libmicrohttpd needs to be compiled from
-source. To install dependencies on Debian jesse, run the following
+On Debian stretch, only GNU libmicrohttpd needs to be compiled from
+source. To install dependencies on Debian stretch, run the following
commands:
- ::
+.. code-block:: console
# apt-get install \
- autoconf \
- automake \
- autopoint \
- libtool \
libltdl-dev \
libunistring-dev \
libsodium-dev \
- libargon2-dev \
+ libargon2-0-dev \
libcurl4-gnutls-dev \
libgcrypt20-dev \
libjansson-dev \
libpq-dev \
- postgresql-9.4
+ postgresql-9.6
# wget https://ftp.gnu.org/gnu/libmicrohttpd/libmicrohttpd-latest.tar.gz
# wget https://ftp.gnu.org/gnu/libmicrohttpd/libmicrohttpd-latest.tar.gz.sig
# gpg -v libmicrohttpd-latest.tar.gz # Should show signed by 939E6BE1E29FC3CC
@@ -469,13 +461,9 @@ commands:
For more recent versions of Debian, you should instead run:
- ::
+.. code-block:: console
# apt-get install \
- autoconf \
- automake \
- autopoint \
- libtool \
libltdl-dev \
libunistring-dev \
libsodium-dev \
@@ -484,9 +472,12 @@ For more recent versions of Debian, you should instead run:
libgcrypt20-dev \
libjansson-dev \
libpq-dev \
- postgresql-9.5 \
+ postgresql-9.6 \
libmicrohttpd-dev
+Note that stretch requires ``libargon2-0-dev``,
+while later versions of Debian require ``libargon2-dev``.
+
For the rest of the installation, follow the generic installation
instructions starting with the installation of libgnunetutil. Note that
if you used the Debian wheezy instructions above, you need to pass
@@ -536,7 +527,7 @@ Service address
The following option sets the transport layer address used by the
merchant backend:
- ::
+.. code-block:: ini
[MERCHANT]/SERVE = TCP | UNIX
@@ -556,10 +547,10 @@ the backend to the network.
To run the Taler backend on TCP port 8888, use:
- ::
+.. code-block:: console
- $ taler-config -s MERCHANT -o SERVE -V TCP
- $ taler-config -s MERCHANT -o PORT -V 8888
+ $ taler-config -s MERCHANT -o SERVE -V TCP
+ $ taler-config -s MERCHANT -o PORT -V 8888
@@ -569,7 +560,7 @@ Currency
Which currency the Web shop deals in, i.e. “EUR” or “USD”, is
specified using the option
- ::
+.. code-block:: ini
[TALER]/CURRENCY
@@ -577,9 +568,9 @@ For testing purposes, the currency MUST match “KUDOS” so that tests
will work with the Taler demonstration exchange at
https://exchange.demo.taler.net/:
- ::
+.. code-block:: console
- $ taler-config -s TALER -o CURRENCY -V KUDOS
+ $ taler-config -s TALER -o CURRENCY -V KUDOS
Database
@@ -588,7 +579,7 @@ Database
In principle is possible for the backend to support different DBMSs.
The option
- ::
+.. code-block:: ini
[MERCHANT]/DB
@@ -600,7 +591,7 @@ DBMS-specific options to access the database.
For postgres, you need to provide:
- ::
+.. code-block:: ini
[MERCHANTDB-postgres]/CONFIG
@@ -610,33 +601,33 @@ Postgres database you want to use. Suppose ``$USER`` is the name of
the user who will run the backend process. Then, you need to first
run
- ::
+.. code-block:: console
- $ sudo -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
as ``$USER`` run:
- ::
+.. code-block:: console
- $ createdb $DBNAME
+ $ createdb $DBNAME
to create the backend’s database. Here, ``$DBNAME`` must match the
database name given in the configuration file.
To configure the Taler backend to use this database, run:
- ::
+.. code-block:: console
- $ taler-config -s MERCHANTDB-postgres -o CONFIG \
- -V postgres:///$DBNAME
+ $ taler-config -s MERCHANTDB-postgres -o CONFIG \
+ -V postgres:///$DBNAME
Now you should create the tables and indices. To do this, run as ``$USER``:
- ::
+.. code-block:: console
- $ taler-merchant-dbinit
+ $ taler-merchant-dbinit
You can improve your security posture if you now REVOKE the rights to CREATE,
@@ -659,29 +650,29 @@ section, the following options need to be configured:
- The “EXCHANGE_BASE_URL” option specifies the exchange’s base URL. For example,
to use the Taler demonstrator, specify:
- ::
+ .. code-block:: console
$ taler-config -s MERCHANT-EXCHANGE-demo \
- -o EXCHANGE_BASE_URL \
- -V https://exchange.demo.taler.net/
+ -o EXCHANGE_BASE_URL \
+ -V https://exchange.demo.taler.net/
- The “MASTER_KEY” option specifies the exchange’s master public key
in base32 encoding. For the Taler demonstrator, use:
- ::
+ .. code-block:: console
$ taler-config -s MERCHANT-EXCHANGE-demo \
- -o MASTER_KEY \
- -V CQQZ9DY3MZ1ARMN5K1VKDETS04Y2QCKMMCFHZSWJWWVN82BTTH00
+ -o MASTER_KEY \
+ -V CQQZ9DY3MZ1ARMN5K1VKDETS04Y2QCKMMCFHZSWJWWVN82BTTH00
- The “CURRENCY” option specifies the exchange’s currency.
For the Taler demonstrator, use:
- ::
+ .. code-block:: console
$ taler-config -s MERCHANT-EXCHANGE-demo \
- -o CURRENCY \
- -V KUDOS
+ -o CURRENCY \
+ -V KUDOS
Note that multiple exchanges can be added to the system by using different
tokens in place of ``demo`` in the example above. Note that all of the
@@ -702,29 +693,29 @@ that section, the following options need to be configured:
- The “AUDITOR_BASE_URL” option specifies the auditor’s base URL. For example,
to use the Taler demonstrator's auditor, specify:
- ::
+ .. code-block:: console
$ taler-config -s MERCHANT-AUDITOR-demo \
- -o AUDITOR_BASE_URL \
- -V https://exchange.demo.taler.net/
+ -o AUDITOR_BASE_URL \
+ -V https://exchange.demo.taler.net/
- The “AUDITOR_KEY” option specifies the auditor's public key
in base32 encoding. For the Taler demonstrator, use:
- ::
+ .. code-block:: console
$ taler-config -s MERCHANT-AUDITOR-demo \
- -o AUDITOR_KEY \
- -V FIXMEBADVALUENEEDTOGETTHERIGHTVALUEHEREEVENTUALLY000
+ -o AUDITOR_KEY \
+ -V FIXMEBADVALUENEEDTOGETTHERIGHTVALUEHEREEVENTUALLY000
- The “CURRENCY” option specifies the auditor’s currency.
For the Taler demonstrator, use:
- ::
+ .. code-block:: console
$ taler-config -s MERCHANT-AUDITOR-demo \
- -o CURRENCY \
- -V KUDOS
+ -o CURRENCY \
+ -V KUDOS
Note that multiple auditors can be added to the system by using different
@@ -743,7 +734,7 @@ Sample backend configuration
The following is an example for a complete backend configuration:
- ::
+.. code-block:: ini
[TALER]
CURRENCY = KUDOS
@@ -792,7 +783,7 @@ Launching the backend
Assuming you have configured everything correctly, you can launch the
merchant backend as ``$USER`` using
- ::
+.. code-block:: console
$ taler-merchant-httpd
@@ -803,13 +794,13 @@ system for how to start and stop daemons.
If everything worked as expected, the command
- ::
+.. code-block:: console
$ curl http://localhost:8888/
should return the message
- ::
+.. code-block:: none
Hello, I'm a merchant's Taler backend. This HTTP server is not for humans.
@@ -865,7 +856,7 @@ With the knowledge of the payto://-URI, instances can be configured by POSTing
a request to :http:post:`/private/instances`. To create a first instance,
create a file ``instance.json`` with an `InstanceConfigurationMessage`
- ::
+.. code-block:: json
{
payto_uris : [ "$PAYTO_URI" ],
@@ -892,7 +883,7 @@ For details, see the :ref:`contract terms <contract-terms>` specification.
You can then create the instance using:
- ::
+.. code-block:: console
$ wget --post-file=instance.json http://localhost:8888/private/instances
@@ -925,10 +916,10 @@ Using UNIX domain sockets
To ensure that the merchant backend is not exposed directly to the network,
you *should* bind the backend to a UNIX domain socket:
- ::
+.. code-block:: console
- $ taler-config -s MERCHANT -o SERVE -V UNIX
- $ taler-config -s MERCHANT -o UNIXPATH -V /some/path/here.sock
+ $ taler-config -s MERCHANT -o SERVE -V UNIX
+ $ taler-config -s MERCHANT -o UNIXPATH -V /some/path/here.sock
Do not use a UNIX domain socket path in "/tmp": systemd (or other init
systems) may give Web servers a private "/tmp" thereby hiding UNIX domain
@@ -948,7 +939,7 @@ Nginx
For Nginx, a possible basic reverse proxy configuration would be:
- ::
+.. code-block:: nginx
proxy_pass http://unix:/some/path/here.sock;
proxy_redirect off;
@@ -967,16 +958,16 @@ Apache
In Apache, make sure you have "mod_proxy", "mod_proxy_http" and
"mod_headers" enabled:
- ::
+.. code-block:: console
- a2enmod proxy
- a2enmod proxy_http
- a2enmod headers
+ $ a2enmod proxy
+ $ a2enmod proxy_http
+ $ a2enmod headers
Then configure your Apache reverse proxy like this (you may change the
endpoint):
- ::
+.. code-block:: apacheconf
<Location "/">
ProxyPass "unix:/some/path/here.sock|http://example.com/"
@@ -1014,7 +1005,7 @@ Nginx
For Nginx, you can implement token-based merchant backend authentication as
follows:
- ::
+.. code-block:: nginx
location ~ /private/ {
if ($http_authorization !~ "(?i)ApiKey SECURITYTOKEN") {
@@ -1033,7 +1024,7 @@ If you are running different instances on the same backend, you
likely will want to specify different access control tokens for
each instance:
- ::
+.. code-block:: nginx
location ~ ^/instances/foo/private/ {
if ($http_authorization !~ "(?i)ApiKey FOOTOKEN") {
@@ -1062,13 +1053,13 @@ Apache
For Apache, you should first enable "mod_rewrite":
- ::
+.. code-block:: console
- a2enmod rewrite
+ $ a2enmod rewrite
Then, you can restrict to an access control token using:
- ::
+.. code-block:: apacheconf
<Location "/">
RewriteEngine On
@@ -1088,7 +1079,7 @@ If you are running different instances on the same backend, you
likely will want to specify different access control tokens for
each instance:
- ::
+.. code-block:: apacheconf
<Location "/instances/foo/">
RewriteEngine On
@@ -1196,17 +1187,17 @@ 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:
- ::
+.. code-block:: console
- $ taler-merchant-dbinit
+ $ 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:
- ::
+.. code-block:: console
- $ taler-merchant-httpd
+ $ taler-merchant-httpd
.. _Tipping-visitors:
@@ -1235,9 +1226,9 @@ First, the reserve must be setup in the merchant backend. A reserve
is always tied to a particular instance. To create a reserve with
10 KUDOS at instance "default" using the demo exchange, use:
- ::
+.. code-block:: console
- $ taler-merchant-setup-reserve \
+ $ taler-merchant-setup-reserve \
-a KUDOS:10 \
-e https://exchange.demo.taler.net/ \
-m http://localhost:8888/instances/default
@@ -1254,7 +1245,7 @@ FIXME: add full example output.
In our example, the output for the wire transfer subject is:
-::
+.. code-block:: none
QPE24X8PBX3BZ6E7GQ5VAVHV32FWTTCADR0TRQ183MSSJD2CHNEG
@@ -1356,7 +1347,7 @@ it under ``$HOME/.config/``.
A config file is a text file containing sections, and each section
contains its values. The right format follows:
-::
+.. code-block:: ini
[section1]
value1 = string
@@ -1375,17 +1366,17 @@ variables that are unset, by using the following syntax:
by defining them under a ``[paths]`` section, see example below,
-::
+.. code-block:: ini
[paths]
TALER_DEPLOYMENT_SHARED = ${HOME}/shared-data
- ..
+ ...
[section-x]
path-x = ${TALER_DEPLOYMENT_SHARED}/x
or by setting them in the environment:
-::
+.. code-block:: console
$ export VAR=/x
@@ -1425,7 +1416,7 @@ file format and can also be edited by hand.
Run
-::
+.. code-block:: console
$ taler-config -s $SECTION
@@ -1433,7 +1424,7 @@ to list all of the configuration values in section ``$SECTION``.
Run
-::
+.. code-block:: console
$ taler-config -s $section -o $option
@@ -1442,7 +1433,7 @@ section ``$section``.
Finally, to change a setting, run
-::
+.. code-block:: console
$ taler-config -s $section -o $option -V $value
@@ -1455,7 +1446,7 @@ their value. To expand the ``$DATADIR`` or other ``$``-variables in the
configuration, pass the ``-f`` option to ``taler-config``. For example,
compare:
-::
+.. code-block:: console
$ taler-config -s PATHS \
-o TALER_DATA_HOME
@@ -1525,10 +1516,10 @@ exist before launching the benchmark. You also
will need to ensure that the Exchange's
details are setup, usually by running
- ::
+.. code-block:: console
- taler-exchange-wire -c $CONFIG_FILE
- taler-exchange-keyup -c $CONFIG_FILE
+ $ taler-exchange-wire -c $CONFIG_FILE
+ $ taler-exchange-keyup -c $CONFIG_FILE
where "$CONFIG_FILE" should be replaced by
the configuration file that is to be used.
@@ -1560,7 +1551,7 @@ Any subcommand is also equipped with the canonical ``--help`` option, so
feel free to issue the following command in order to explore all the
possibilities. For example:
-::
+.. code-block:: console
$ taler-merchant-benchmark corner --help
@@ -1619,14 +1610,14 @@ Because all of the Docker source file are kept in our “deployment“
repository, we start by checking out the ``git://git.taler.net/deployment``
codebase:
-::
+.. code-block:: console
$ git clone git://git.taler.net/deployment
Now we actually build the merchant’s image. From the same directory as
above:
-::
+.. code-block:: console
$ cd deployment/docker/merchant/
$ docker-compose build
@@ -1634,7 +1625,7 @@ above:
If everything worked as expected, the merchant is ready to be launched.
From the same directory as the previous step:
-::
+.. code-block:: console
# Recall: the docker-machine should be up and running.
$ docker-compose up
@@ -1646,7 +1637,7 @@ message from postresql about already existing roles and databases.
To test if everything worked as expected, it suffices to issue a simple
request to the merchant, as:
-::
+.. code-block:: console
$ curl http://$(docker-machine ip)/
# A greeting message should be returned by the merchant.