summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--taler-merchant-manual.rst110
1 files changed, 79 insertions, 31 deletions
diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst
index 3b0aba08..5626568e 100644
--- a/taler-merchant-manual.rst
+++ b/taler-merchant-manual.rst
@@ -16,7 +16,7 @@ GNU Taler is compatible with anti-money-laundering (AML) and
know-your-customer (KYC) regulation, as well as data protection
regulation (such as GDPR).
-GNU Taler is not yet production-ready, after following this manual you
+GNU Taler is not yet production-ready: after following this manual you
will have a backend that can process payments in “KUDOS”, but not
regular currencies. This is not so much because of limitations in the
backend, but because we are not aware of a Taler exchange operator
@@ -27,14 +27,14 @@ offering regular currencies today.
About this manual
-----------------
-This tutorial targets system administrators who want to install a GNU
+This manual targets system administrators who want to install a GNU
Taler merchant *backend*.
We expect some moderate familiarity with the compilation and
-installation of free software packages. An understanding of cryptography
+installation of Free Software packages. An understanding of cryptography
is not required.
-This first chapter of the tutorial will give a brief overview of the
+This first chapter of the manual will give a brief overview of the
overall Taler architecture, describing the environment in which the
Taler backend operates. The second chapter then explains how to install
the software, including key dependencies. The third chapter will explain
@@ -295,8 +295,6 @@ backend:
- libcurl >= 7.26 (or libgnurl >= 7.26)
-- GNU libmicrohttpd >= 0.9.71
-
- libqrencode >= 4.0.0
- GNU libgcrypt >= 1.6
@@ -311,13 +309,16 @@ backend:
- Postgres >= 9.6, including libpq
-- GNUnet (from Git)
+- GNU libmicrohttpd >= 0.9.71
-- GNU Taler exchange (from Git)
+- GNUnet (from Git or see release announcement)
-Except for the last two, these are available in most GNU/Linux
-distributions and should just be installed using the respective package
-manager.
+- GNU Taler exchange (from Git or see release announcement)
+
+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.
The following sections will provide detailed instructions for installing
the libgnunetutil and GNU Taler exchange dependencies.
@@ -823,14 +824,49 @@ Instance setup
Before using the backend, you must at least configure the "default" instance.
-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`
+
+KUDOS Accounts
+--------------
+
+The main configuration data that must be provided for each instance
+is the bank account information.
+
+In order to receive payments, the merchant backend needs to
+communicate bank account details to the exchange.
+
+The bank account information is provided in the form of a ``payto://``-URI.
+See RFC 8905 for the format of ``payto://``-URIs.
+
+For first tests, you should sign up for a KUDOS bank
+account at `https://bank.demo.taler.net/ <https://bank.demo.taler.net/>`_.
+In this case, the payto://-URI will be of the form
+"payto://x-taler-bank/bank.demo.taler.net/$USERNAME" where "$USERNAME"
+must be replaced with the name of the account that was established
+at `https://bank.demo.taler.net/ <https://bank.demo.taler.net/>`_.
+
+
+IBAN Accounts
+-------------
+
+When deploying Taler with the real banking system, you primarily need to
+change the currency of the configuration from KUDOS to the actual currency
+(such as EUR, USD, CHF) and provide a payto://-URI of your real bank
+account. In Europe, this will involve knowing your IBAN number. If you have an
+IBAN, the corresponding payto://-URI is simply "payto://iban/$IBAN" where
+"$IBAN" must be replaced with the actual IBAN number.
+
+
+Setup
+------
+
+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`
::
{
- payto_uris : [ "payto://iban/IBANNUMBERHERE" ],
+ payto_uris : [ "$PAYTO_URI" ],
id : "default",
name: "example.com",
address: { country : "zz" },
@@ -842,6 +878,16 @@ Instances can be configured by POSTing a request to
default_pay_delay: { d_ms : 1209600000 },
}
+In the text above, you must replace "$PAYTO_URI" with your actual
+payto://-URI. Also, be sure to replace KUDOS with the fiat currency if the
+setup is for an actual bank. The "name" field will be shown as the name of
+your shop. The "address" field is expected to contain your shop's physical
+address. The various defaults specify defaults for transaction fees your shop
+is willing to cover, how long offers made to the customer are valid, and how
+long the exchange has before it must wire the funds to your bank
+account. Those defaults can be modified for individual orders.
+For details, see the :ref:`contract terms <contract-terms>` specification.
+
You can then create the instance using:
::
@@ -857,21 +903,6 @@ or purge (deleting all associated data) instances exist as well and are document
in the :ref:`Merchant Backend API documentation <merchant-api>`.
-Accounts
---------
-
-The main configuration data that must be provided for each instance
-is the bank account information.
-
-In order to receive payments, the merchant backend needs to
-communicate bank account details to the exchange.
-
-The bank account information is provided in the form of a ``payto://``-URL.
-
-See RFC XXXX for the format of ``payto://``-URLs.
-
-
-
.. _Secure-setup:
Secure setup
@@ -890,13 +921,18 @@ 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:
+you *should* bind the backend to a UNIX domain socket:
::
$ taler-config -s MERCHANT -o SERVE -V UNIX
$ taler-config -s MERCHANT -o UNIXPATH -V /some/path/here.sock
+Alternatively, you *may* use a host-based firewall to block access
+to the TCP port of the merchant backend, but this is *not recommended*.
+Relying on NAT or network firewalls for access control is gross negligence.
+
+
Reverse proxy configuration
---------------------------
@@ -915,6 +951,18 @@ 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 ``SERVE`` configuration.
+In Apache, make sure you have "mod_proxy" enabled (a2enmod mod_proxy)
+and set:
+
+ ::
+
+ <Location "/">
+ ProxyPass "unix:/some/path/here.sock"
+ RequestHeader add "X-Forwarded-Proto" "https"
+ </Location>
+ FIXME: above is untested and incomplete
+
+
Access control
--------------