diff options
Diffstat (limited to 'taler-merchant-manual.rst')
| -rw-r--r-- | taler-merchant-manual.rst | 251 |
1 files changed, 121 insertions, 130 deletions
diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst index a49b9163..bff0e84d 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. |