diff options
Diffstat (limited to 'taler-merchant-manual.rst')
| -rw-r--r-- | taler-merchant-manual.rst | 1361 |
1 files changed, 859 insertions, 502 deletions
diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst index 0ac0ca55..f48fb07a 100644 --- a/taler-merchant-manual.rst +++ b/taler-merchant-manual.rst @@ -50,8 +50,9 @@ operating a basic backend. Architecture overview --------------------- -crypto-currency -KUDOS +.. index:: crypto-currency +.. index:: KUDOS + Taler is a pure payment system, not a new crypto-currency. As such, it operates in a traditional banking context. In particular, this means that in order to receive funds via Taler, the merchant must have a @@ -59,111 +60,194 @@ regular bank account, and payments can be executed in ordinary currencies such as USD or EUR. For testing purposes, Taler uses a special currency “KUDOS” and includes its own special bank. +.. index:: frontend +.. index:: back office +.. index:: backend +.. index:: DBMS +.. index:: Postgres + The Taler software stack for a merchant consists of four main components: -- frontend - A frontend which interacts with the customer’s browser. The frontend +- A frontend which interacts with the customer’s browser. The frontend enables the customer to build a shopping cart and place an order. Upon payment, it triggers the respective business logic to satisfy the order. This component is not included with Taler, but rather - assumed to exist at the merchant. This manual describes how to - integrate Taler with Web shop frontends. - -- back office - A back office application that enables the shop operators to view + assumed to exist at the merchant. + The :ref:`Merchant API Tutorial <merchant-api-tutorial>` gives an + introduction for how to integrate Taler with Web shop frontends. +- A back office application that enables the shop operators to view customer orders, match them to financial transfers, and possibly approve refunds if an order cannot be satisfied. This component is - again not included with Taler, but rather assumed to exist at the - merchant. This manual will describe how to integrate such a component - to handle payments managed by Taler. - -- backend - A Taler-specific payment backend which makes it easy for the frontend - to process financial transactions with Taler. The next two chapters - will describe how to install and configure this backend. - -- DBMS - Postgres - A DBMS which stores the transaction history for the Taler backend. + not included with Taler, but rather assumed to exist at the + merchant. The :ref:`Merchant Backend API <merchant-api>` provides + the API specification that should be reviewed to integrate such a + back office with the Taler backend. +- A Taler-specific payment backend which makes it easy for the frontend + to process financial transactions with Taler. This manual primarily + describes how to install and configure this backend. +- A DBMS which stores the transaction history for the Taler backend. For now, the GNU Taler reference implemenation only supports Postgres, but the code could be easily extended to support another - DBMS. + DBMS. Please review the Postgres documentation for details on + how to configure the database. The following image illustrates the various interactions of these key components: -:: - - Missing diagram image - -RESTful -Basically, the backend provides the cryptographic protocol support, -stores Taler-specific financial information in a DBMS and communicates -with the GNU Taler exchange over the Internet. The frontend accesses the -backend via a RESTful API. As a result, the frontend never has to -directly communicate with the exchange, and also does not deal with -sensitive data. In particular, the merchant’s signing keys and bank -account information is encapsulated within the Taler backend. - -Installation -============ - -This chapter describes how to install the GNU Taler merchant backend. - -Installing Taler using Docker ------------------------------ - -This section provides instructions for the merchant backend installation -using ‘Docker‘. - -For security reasons, we run Docker against a VirtualBox instance, so -the ``docker`` command should connect to a ``docker-machine`` instance -that uses the VirtualBox driver. +.. image:: arch-api.png -Therefore, the needed tools are: “docker“, “docker-machine“, and -“docker-compose“. Please refer to Docker’s official [1]_ documentation -in order to get those components installed, as that is not in this -manual’s scope. +.. index:: RESTful -Before starting to build the merchant’s image, make sure a -“docker-machine“ instance is up and running. - -Because all of the Docker source file are kept in our “deployment“ -repository, we start by checking out the ``git://taler.net/deployment`` -codebase: +Basically, the backend provides the cryptographic protocol support, stores +Taler-specific financial information in a DBMS and communicates with the GNU +Taler exchange over the Internet. The frontend accesses the backend via a +RESTful API. As a result, the frontend never has to directly communicate with +the exchange, and also does not deal with sensitive data. In particular, the +merchant’s signing keys and bank account information is encapsulated within +the Taler backend. -:: +A typical deployment will additionally include a full-blown Web server (like +Apache or Nginx). Such a Web server would be responsible for TLS termination +and access control to the /private/ API endpoints of the merchant backend. +Please carefully review the section on :ref:`Secure setup <Secure-setup>` before +deploying a Taler merchant backend to production. - $ git clone git://taler.net/deployment -Now we actually build the merchant’s image. From the same directory as -above: +Terminology +=========== -:: +This chapter describes some of the key concepts used throughout the manual. - $ cd deployment/docker/merchant/ - $ docker-compose build +Instances +--------- -If everything worked as expected, the merchant is ready to be launched. -From the same directory as the previous step: +.. index:: instance -:: +The backend allows the user to run multiple *instances* of shops with distinct +business entities sharing a single backend. Each instance uses its own bank +accounts and key for signing contracts. All major accounting functionality is +separate per instance. What is shared is the database, HTTP(S) address and +the main Taler configuration (accepted currency, exchanges and auditors). - # Recall: the docker-machine should be up and running. - $ docker-compose up +Accounts +-------- + +.. index:: account + +To receive payments, an instance must have configured one or more bank +*accounts*. The backend does not have accounts for users, and instances are +also not really 'accounts'. So whenever we use the term *account*, it is about +a bank account of a merchant. + +Inventory +--------- + +.. index:: inventory +.. index:: product +.. index:: lock +.. index:: unit +.. index:: order + +The Taler backend offers inventory management as an optional function. +Inventory is tracked per instance and consists of *products* sold in +*units*. Inventory can be finite or infinite (for digital products). +Products may include previews (images) to be shown to the user and other +meta-data. Inventory management allows the frontend to *lock* products, +reserving them for a particular (unpaid) *order*. The backend can keep +track of how many units of a product remain in stock and ensure that +the number of units sold does not exceed the number of units in stock. + +Inventory management is optional, and it is possible for the frontend to +include products in orders that are not in the inventory, or to override +prices of products in the inventory. + +Orders and Contracts +-------------------- -You should see some live logging from all the involved containers. At -this stage of development, you should also ignore some (harmless) error -message from postresql about already existing roles and databases. +.. index:: order +.. index:: contract +.. index:: claim +.. index:: pay +.. index:: refund +.. index:: wire deadline +.. index:: lock +.. index:: legal expiration + +In Taler, users pay merchants for orders. An order is first created by the +merchant, where the merchant specifies the specific terms of the order. + +After an order is created, it is *claimed* by a wallet. Once an order is +claimed by a specific wallet, only that wallet will be able to pay for this +order, to the exclusion of other wallets even if they see the same order URL. + +A wallet may *pay* for a claimed order, at which point the order turns into +a (paid) contract. Orders have an expiration date after which the commercial +offer expires and any stock of products *locked* by the order is released, +allowing the stock to be sold in other orders. + +Once a contract has been paid, the merchant should fulfill the contract. It +is possible for the merchant to *refund* a contract order, for example if the +contract cannot be fulfilled after all. Refunds are only possible until the +exchange has *wired* the payment to the merchant. Once the funds have been +wired, refunds are no longer allowed by the Taler exchange. The *wire +deadline* specifies the latest time by which an exchange must wire the funds, +while the (earlier) *refund deadline* specifies the earliest time when an +exchange may wire the funds. + +Contract information is kept for legal reasons, typically to provide tax +records in case of a tax audit. After the *legal expiration* (by default a +decade), contract information is deleted. + +Transfers +--------- + +.. index:: transfer +.. index:: wire transfer + +The Taler backend can be used to verify that the exchange correctly wired all +of the funds to the merchant. However, the backend does not have access to the +incoming wire transfers of the merchant's bank account. Thus, merchants must +manually provide the backend with wire *transfer* data that specifies the wire +transfer subject and the amount that was received. Given this information, the +backend can detect and report any irregularities that might arise. + +Tipping +------- + +.. index:: tip +.. index:: grant +.. index:: pick up + +Taler does not only allow a Website to be paid, but also to make voluntary, +non-contractual payments to visitors, called *tips*. Such tips could be +granted as a reward for filling in surveys or watching advertisements. For +tips, there is no contract, tips are always voluntary actions by the Web +site that do not arise from a contractual obligation. Before a Web site +can create tips, it must establish a reserve. Once a reserve has been +established, the merchant can *grant* tips, allowing wallets to *pick up* +the tip. + +Reserves +-------- + +.. index:: reserve +.. index:: close + +A *reserve* is a pool of electronic cash at an exchange under the control of +a private key. Merchants withdraw coins from a reserve when granting +tips. A reserve is established by first generating the required key material +in the merchant backend, and then wiring the desired amount of funds to the +exchange. + +An exchange will automatically *close* a reserve after a fixed period of time +(typically about a month), wiring any remaining funds back to the merchant. -To test if everything worked as expected, it suffices to issue a simple -request to the merchant, as: -:: +Installation +============ - $ curl http://$(docker-machine ip)/ - # A greeting message should be returned by the merchant. +This chapter describes how to install the GNU Taler merchant backend. .. _Generic-instructions: @@ -181,7 +265,7 @@ system. .. _Installation-of-dependencies: Installation of dependencies -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The following packages need to be installed before we can compile the backend: @@ -200,15 +284,21 @@ backend: - libcurl >= 7.26 (or libgnurl >= 7.26) -- GNU libmicrohttpd >= 0.9.39 +- GNU libmicrohttpd >= 0.9.71 - GNU libgcrypt >= 1.6 +- libsodium >= 1.0 + +- 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.4, including libpq +- Postgres >= 9.6, including libpq -- libgnunetutil (from Git) +- GNUnet (from Git) - GNU Taler exchange (from Git) @@ -221,19 +311,20 @@ the libgnunetutil and GNU Taler exchange dependencies. .. _Installing-libgnunetutil: -Installing libgnunetutil -~~~~~~~~~~~~~~~~~~~~~~~~ +Installing GNUnet +^^^^^^^^^^^^^^^^^ -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. +.. index:: GNUnet -To download and install libgnunetutil, proceed as follows: +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: :: - $ git clone https://gnunet.org/git/gnunet/ + $ git clone https://git.gnunet.org/gnunet/ $ cd gnunet/ $ ./bootstrap $ ./configure [--prefix=GNUNETPFX] @@ -245,73 +336,98 @@ 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 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. index:: exchange -exchange After installing GNUnet, you can download and install the exchange as follows: -:: + :: - $ git clone git://taler.net/exchange - $ 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 + $ git clone https://git.taler.net/exchange/ + $ 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 + +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! -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. .. _Installing-the-GNU-Taler-merchant-backend: Installing the GNU Taler merchant backend -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. index:: backend -backend The following steps assume all dependencies are installed. Use the following commands to download and install the merchant backend: -:: + :: - $ git clone git://taler.net/merchant - $ cd merchant - $ ./bootstrap - $ ./configure [--prefix=PFX] \ - [--with-gnunet=GNUNETPFX] \ - [--with-exchange=EXCHANGEPFX] - $ # Each dependency can be fetched from non standard locations via - $ # the '--with-<LIBNAME>' option. See './configure --help'. - $ make - $ make install + $ git clone https://git.taler.net/merchant/ + $ cd merchant + $ ./bootstrap + $ ./configure [--prefix=PFX] \ + [--with-gnunet=GNUNETPFX] \ + [--with-exchange=EXCHANGEPFX] + $ # 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``. -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 ------------------------------------ -Wheezy -Debian +.. index:: Wheezy +.. index:: Debian + Debian wheezy is too old and lacks most of the packages required. On Debian jessie, only GNU libmicrohttpd needs to be compiled from source. To install dependencies on Debian jesse, run the following commands: -:: + :: # apt-get install \ autoconf \ @@ -320,6 +436,8 @@ commands: libtool \ libltdl-dev \ libunistring-dev \ + libsodium-dev \ + libargon2-dev \ libcurl4-gnutls-dev \ libgcrypt20-dev \ libjansson-dev \ @@ -335,7 +453,7 @@ commands: For more recent versions of Debian, you should instead run: -:: + :: # apt-get install \ autoconf \ @@ -344,6 +462,8 @@ For more recent versions of Debian, you should instead run: libtool \ libltdl-dev \ libunistring-dev \ + libsodium-dev \ + libargon2-dev \ libcurl4-gnutls-dev \ libgcrypt20-dev \ libjansson-dev \ @@ -356,11 +476,13 @@ instructions starting with the installation of libgnunetutil. Note that if you used the Debian wheezy instructions above, you need to pass ``--with-microhttpd=/usr/local/`` to all ``configure`` invocations. + How to configure the merchant’s backend ======================================= -taler-config -taler.conf +.. index:: taler-config +.. index:: taler.conf + The installation already provides reasonable defaults for most of the configuration options. However, some must be provided, in particular the database account and bank account that the backend should use. By @@ -376,21 +498,33 @@ see `Using taler-config <#Using-taler_002dconfig>`__. Backend options --------------- +.. index:: DBMS +.. index:: Postgres +.. index:: UNIX domain socket +.. index:: TCP +.. index:: port +.. index:: currency +.. index:: KUDOS +.. index:: exchange +.. index:: instance +.. index:: wire format + The following table describes the options that commonly need to be modified. Here, the notation ``[$section]/$option`` denotes the option ``$option`` under the section ``[$section]`` in the configuration file. + Service address - The following option sets the transport layer address used by the - merchant backend: +^^^^^^^^^^^^^^^ + +The following option sets the transport layer address used by the +merchant backend: - UNIX domain socket - TCP :: [MERCHANT]/SERVE = TCP | UNIX - If given, +If given, - ``TCP``, then we need to set the TCP port in ``[MERCHANT]/PORT`` @@ -399,197 +533,201 @@ Service address latter takes the usual permission mask given as a number, e.g. 660 for user/group read-write access. - The frontend can then connect to the backend over HTTP using the - specified address. If frontend and backend run within the same - operating system, the use of a UNIX domain socket is recommended to - avoid accidentally exposing the backend to the network. +The frontend can then connect to the backend over HTTP using the specified +address. If frontend and backend run within the same operating system, the +use of a UNIX domain socket is recommended to avoid accidentally exposing +the backend to the network. - port - To run the Taler backend on TCP port 8888, use: +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 - Which currency the Web shop deals in, i.e. “EUR” or “USD”, is - specified using the option +^^^^^^^^ + +Which currency the Web shop deals in, i.e. “EUR” or “USD”, is +specified using the option - currency - KUDOS :: [TALER]/CURRENCY - For testing purposes, the currency MUST match “KUDOS” so that tests - will work with the Taler demonstration exchange at - https://exchange.demo.taler.net/: +For testing purposes, the currency MUST match “KUDOS” so that tests +will work with the Taler demonstration exchange at +https://exchange.demo.taler.net/: :: $ taler-config -s TALER -o CURRENCY -V KUDOS + Database - DBMS - In principle is possible for the backend to support different DBMSs. - The option +^^^^^^^^ + +In principle is possible for the backend to support different DBMSs. +The option :: [MERCHANT]/DB - specifies which DBMS is to be used. However, currently only the value - "postgres" is supported. This is also the default. +specifies which DBMS is to be used. However, currently only the value +"postgres" is supported. This is also the default. - In addition to selecting the DBMS software, the backend requires - DBMS-specific options to access the database. +In addition to selecting the DBMS software, the backend requires +DBMS-specific options to access the database. - For postgres, you need to provide: +For postgres, you need to provide: :: [merchantdb-postgres]/config - Postgres - This option specifies a postgres access path using the format - ``postgres:///$DBNAME``, where ``$DBNAME`` is the name of the - 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 +This option specifies a postgres access path using the format +``postgres:///$DBNAME``, where ``$DBNAME`` is the name of the +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 :: - $ 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 - as ``$USER`` run: +as the Postgres database administrator (usually ``postgres``) to +grant ``$USER`` the ability to create new databases. Next, you should +as ``$USER`` run: :: $ createdb $DBNAME - to create the backend’s database. Here, ``$DBNAME`` must match the - database name given in the configuration file. +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: +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 - exchange - To add an exchange to the list of trusted payment service providers, - you create a section with a name that starts with “exchange-”. In - that section, the following options need to be configured: +^^^^^^^^ - - The “url” option specifies the exchange’s base URL. For example, - to use the Taler demonstrator use: +To add an exchange to the list of trusted payment service providers, you +create a section with a name that starts with “MERCHANT-EXCHANGE-”. In that +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: :: - $ taler-config -s EXCHANGE-demo -o URL \ + $ taler-config -s MERCHANT-EXCHANGE-demo \ + -o EXCHANGE_BASE_URL \ -V https://exchange.demo.taler.net/ - - master key - The “master_key” option specifies the exchange’s master public key + - The “MASTER_KEY” option specifies the exchange’s master public key in base32 encoding. For the Taler demonstrator, use: :: - $ taler-config -s EXCHANGE-demo -o master_key \ + $ taler-config -s MERCHANT-EXCHANGE-demo \ + -o MASTER_KEY \ -V CQQZ9DY3MZ1ARMN5K1VKDETS04Y2QCKMMCFHZSWJWWVN82BTTH00 - 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 exchanges must use the same currency. If you need - to support multiple currencies, you need to configure a backend - per currency. - -Instances - instance - The backend allows the user to run multiple instances of shops with - distinct business entities against a single backend. Each instance - uses its own bank accounts and key for signing contracts. It is - mandatory to configure a "default" instance. - - - The “KEYFILE” option specifies the file containing the instance’s - private signing key. For example, use: + - The “CURRENCY” option specifies the exchange’s currency. + For the Taler demonstrator, use: :: - $ taler-config -s INSTANCE-default -o KEYFILE \ - -V '${TALER_CONFIG_HOME}/merchant/instace/default.key' + $ taler-config -s MERCHANT-EXCHANGE-demo \ + -o CURRENCY \ + -V KUDOS - - The “NAME” option specifies a human-readable name for the - instance. For example, use: +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 +exchanges must use the same currency: If the currency does not match the main +currency from the "TALER" section, the exchange is ignored. If you need to +support multiple currencies, you need to configure a backend per currency. - :: - $ taler-config -s INSTANCE-default -o NAME \ - -V 'Kudos Inc.' - - The optional “TIP_EXCHANGE” and “TIP_EXCHANGE_PRIV_FILENAME” - options are discussed in Tipping visitors +Auditor +^^^^^^^ -Accounts - wire format - In order to receive payments, the merchant backend needs to - communicate bank account details to the exchange. For this, the - configuration must include one or more sections named “ACCOUNT-name” - where ``name`` can be replaced by some human-readable word - identifying the account. For each section, the following options - should be provided: +To add an auditor to the list of trusted auditors (which implies +that all exchanges audited by this auditor will be trusted!) +you create a section with a name that starts with “MERCHANT-AUDITOR-”. In +that section, the following options need to be configured: - - The “URL” option specifies a ``payto://``-URL for the account of - the merchant. For example, use: + - The “AUDITOR_BASE_URL” option specifies the auditor’s base URL. For example, + to use the Taler demonstrator's auditor, specify: :: - $ taler-config -s ACCOUNT-bank -o NAME \ - -V 'payto://x-taler-bank/bank.demo.taler.net/4' + $ taler-config -s MERCHANT-AUDITOR-demo \ + -o AUDITOR_BASE_URL \ + -V https://exchange.demo.taler.net/ - - The “WIRE_RESPONSE” option specifies where Taler should store the - (salted) JSON encoding of the wire account. The file given will be - created if it does not exist. For example, use: + - The “AUDITOR_KEY” option specifies the auditor's public key + in base32 encoding. For the Taler demonstrator, use: :: - $ taler-config -s ACCOUNT-bank -o WIRE_RESPONSE \ - -V '{$TALER_CONFIG_HOME}/merchant/bank.json' + $ taler-config -s MERCHANT-AUDITOR-demo \ + -o AUDITOR_KEY \ + -V FIXMEBADVALUENEEDTOGETTHERIGHTVALUEHEREEVENTUALLY000 - - For each ``instance`` that should use this account, you should set - ``HONOR_instance`` and ``ACTIVE_instance`` to YES. The first - option will cause the instance to accept payments to the account - (for existing contracts), while the second will cause the backend - to include the account as a possible option for new contracts. - - For example, use: + - The “CURRENCY” option specifies the auditor’s currency. + For the Taler demonstrator, use: :: - $ taler-config -s ACCOUNT-bank -o HONOR_default \ - -V YES - $ taler-config -s ACCOUNT-bank -o ACTIVE_default \ - -V YES + $ taler-config -s MERCHANT-AUDITOR-demo \ + -o CURRENCY \ + -V KUDOS + - to use “account-bank” for the “default” instance. +Note that multiple auditors can be added to the system by using different +tokens in place of ``demo`` in the example above. Note that all of the +auditors must use the same currency: If the currency does not match the main +currency from the "TALER" section, the auditor is ignored. If you need to +support multiple currencies, you need to configure a backend per currency. - Note that additional instances can be specified using different - tokens in the section name instead of ``default``. .. _Sample-backend-configuration: Sample backend configuration ---------------------------- -configuration +.. index:: configuration + The following is an example for a complete backend configuration: -:: + :: [TALER] CURRENCY = KUDOS @@ -602,22 +740,18 @@ The following is an example for a complete backend configuration: [MERCHANTDB-postgres] CONFIG = postgres:///donations - [INSTANCE-default] - KEYFILE = $DATADIR/key.priv - NAME = "Kudos Inc." - - [ACCOUNT-bank] - URL = payto://x-taler-bank/bank.demo.taler.net/4 - WIRE_RESPONSE = $DATADIR/bank.json - HONOR_default = YES - ACTIVE_default = YES - TALER_BANK_AUTH_METHOD = basic - USERNAME = my_user - PASSWORD = 1234pass - - [EXCHANGE-trusted] - URL = https://exchange.demo.taler.net/ + [merchant-exchange-NAME] + EXCHANGE_BASE_URL = https://exchange.demo.taler.net/ MASTER_KEY = CQQZ9DY3MZ1ARMN5K1VKDETS04Y2QCKMMCFHZSWJWWVN82BTTH00 + # If currency does not match [TALER] section, the exchange + # will be ignored! + CURRENCY = KUDOS + + [merchant-auditor-NAME] + AUDITOR_BASE_URL = https://auditor.demo.taler.net/ + AUDITOR_KEY = DSDASDXAMDAARMNAD53ZA4AFAHA2QADAMAHHASWDAWXN84SDAA11 + # If currency does not match [TALER] section, the auditor + # will be ignored! CURRENCY = KUDOS Given the above configuration, the backend will use a database named @@ -636,147 +770,324 @@ them. Launching the backend --------------------- -backend -taler-merchant-httpd +.. index:: 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 + + :: $ curl http://localhost:8888/ should return the message -:: + :: Hello, I'm a merchant's Taler backend. This HTTP server is not for humans. 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 :ref:`Secure setup <Secure-setup>`. -.. _Testing: -Testing -======= +.. index:: instance +.. _Instance-setup: -The tool ``taler-merchant-generate-payments`` can be used to test the -merchant backend installation. It implements all the payment’s steps in -a programmatically way, relying on the backend you give it as input. -Note that this tool gets installed along all the merchant backend’s -binaries. +Instance setup +============== -This tool gets configured by a config file, that must have the following -layout: +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` - [PAYMENTS-GENERATOR] + :: - # The exchange used during the test: make sure the merchant backend - # being tested accpets this exchange. - # If the sysadmin wants, she can also install a local exchange - # and test against it. - EXCHANGE = https://exchange.demo.taler.net/ + { + payto_uris : [ "payto://iban/IBANNUMBERHERE" ], + id : "default", + name: "example.com", + address: { country : "zz" }, + jurisdiction: { country : "zz" }, + default_max_wire_fee: "KUDOS:1", + default_wire_fee_amortization: 100, + default_max_deposit_fee: "KUDOS:1", + default_wire_transfer_delay: { d_ms : 1209600000 }, + default_pay_delay: { d_ms : 1209600000 }, + } - # This value must indicate some URL where the backend - # to be tested is listening; it doesn't have to be the - # "official" one, though. - MERCHANT = http://localbackend/ +You can then create the instance using: - # This value is used when the tool tries to withdraw coins, - # and must match the bank used by the exchange. If the test is - # done against the exchange at https://exchange.demo.taler.net/, - # then this value can be "https://bank.demo.taler.net/". - BANK = https://bank.demo.taler.net/ + :: - # The merchant instance in charge of serving the payment. - # Make sure this instance has a bank account at the same bank - # indicated by the 'bank' option above. - INSTANCE = default + $ wget --post-file=instance.json http://localhost:8888/private/instances - # The currency used during the test. Must match the one used - # by merchant backend and exchange. - CURRENCY = KUDOS +The base URL for the instance will then be +``http://localhost:8888/instances/default``. You can create additional +instances by changing the "id" value to identifies other than "default". -Run the test in the following way: +Endpoints to modify (reconfigure), permanently disable (while keeping the data) +or purge (deleting all associated data) instances exist as well and are documented +in the :ref:`Merchant Backend API documentation <merchant-api>`. -:: - $ taler-merchant-generate-payments [-c config] [-e EURL] [-m MURL] +Accounts +-------- -The argument ``config`` given to ``-c`` points to the configuration file -and is optional – ``~/.config/taler.conf`` will be checked by default. -By default, the tool forks two processes: one for the merchant backend, -and one for the exchange. The option ``-e`` (``-m``) avoids any exchange -(merchant backend) fork, and just runs the generator against the -exchange (merchant backend) running at ``EURL`` (``MURL``). +The main configuration data that must be provided for each instance +is the bank account information. -Please NOTE that the generator contains *hardcoded* values, as for -deposit fees of the coins it uses. In order to work against the used -exchange, those values MUST match the ones used by the exchange. +In order to receive payments, the merchant backend needs to +communicate bank account details to the exchange. -The following example shows how the generator "sets" a deposit fee of -EUR:0.01 for the 5 EURO coin. +The bank account information is provided in the form of a ``payto://``-URL. -:: +See RFC XXXX for the format of ``payto://``-URLs. - // from <merchant_repository>/src/sample/generate_payments.c - { .oc = OC_PAY, - .label = "deposit-simple", - .expected_response_code = MHD_HTTP_OK, - .details.pay.contract_ref = "create-proposal-1", - .details.pay.coin_ref = "withdraw-coin-1", - .details.pay.amount_with_fee = concat_amount (currency, "5"), - .details.pay.amount_without_fee = concat_amount (currency, "4.99") }, -The logic calculates the deposit fee according to the subtraction: -``amount_with_fee - amount_without_fee``. -The following example shows a 5 EURO coin configuration - needed by the -used exchange - which is compatible with the hardcoded example above. +.. _Secure-setup: -:: +Secure setup +============ - [COIN_eur_5] - value = EUR:5 - duration_overlap = 5 minutes - duration_withdraw = 7 days - duration_spend = 2 years - duration_legal = 3 years - fee_withdraw = EUR:0.00 - fee_deposit = EUR:0.01 # important bit - fee_refresh = EUR:0.00 - fee_refund = EUR:0.00 - rsa_keysize = 1024 +.. index:: security +.. index:: TLS -If the command terminates with no errors, then the merchant backend is -correctly installed. +The Taler backend does not include even the most basic forms of +access control or transport layer security. Thus, production +setups **must** deploy the Taler backend behind an HTTP(S) server +that acts as a *reverse proxy*, performs TLS termination and +authentication and then forwards requests to the backend. -After this operation is done, the merchant database will have some dummy -data in it, so it may be convenient to clean all the tables; to this -purpose, issue the following command: +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: + + :: + + $ taler-config -s MERCHANT -o SERVE -V UNIX + $ taler-config -s MERCHANT -o UNIXPATH -V /some/path/here.sock + +Reverse proxy configuration +--------------------------- + +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 ``SERVE`` configuration. + +Access control +-------------- + +All endpoints with /private/ in the URL must be restricted to authorized users +of the respective instance. Specifically, the HTTP server must be configured +to only allow access to ``$BASE_URL/private/`` to the authorized users of the +default instance, and to ``$BASE_URL/instances/$ID/private/`` to the +authorized users of the instance ``$ID``. + +How access control is done (TLS client authentication, HTTP basic or digest +authentication, etc.) is completely up to the merchant and does not matter to +the Taler merchant backend. + +Note that all of the other endpoints (without /private/) are expected to be +fully exposed to the Internet, and wallets may have to interact with those +endpoints directly without client authentication. + + + +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 + + +.. _Tipping-visitors: + +Tipping visitors +================ + +.. index:: tipping + +Taler can also be used to tip Web site visitors. For example, you may be +running an online survey, and you want to reward those people that have +dutifully completed the survey. If they have installed a Taler wallet, +you can provide them with a tip for their deeds. This section describes +how to setup the Taler merchant backend for tipping. + +There are three basic steps that must happen to tip a visitor. + +.. _Fund-the-reserve: + +Fund the reserve +---------------- + +.. index:: reserve + +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: + + :: + + $ taler-merchant-setup-reserve \ + -a KUDOS:10 \ + -e https://exchange.demo.taler.net/ \ + -m http://localhost:8888/instances/default + +The above command assumes that the merchant runs on localhost on +port 8888. The current implementation of the tool does not yet support +transmission of authentication information to the backend +(`see bug 6418 <https://bugs.gnunet.org/view.php?id=6418>`_). + +The command will output a payto:// URI which specifies where to +wire the funds and which wire transfer subject to use. + +FIXME: add full example output. + +In our example, the output for the wire transfer subject is: :: - $ taler-merchant-dbinit -r + QPE24X8PBX3BZ6E7GQ5VAVHV32FWTTCADR0TRQ183MSSJD2CHNEG + +You now need to make a wire transfer to the exchange’s bank account +using the given wire transfer subject. + +Make your wire transfer and (optionally) check at +“https://exchange/reserves/QPE24X...” whether your transfer has arrived at the +exchange. + +Once the funds have arrived, you can start to use the reserve for +tipping. + +Note that an exchange will typically close a reserve after four weeks, wiring +all remaining funds back to the sender’s account. Thus, you should plan to +wire funds corresponding to a campaign of about two weeks to the exchange +initially. If your campaign runs longer, you should setup another reserve +every other week to ensure one is always ready. + +.. _Authorize-a-tip: + +Authorize a tip +--------------- + +When your frontend has reached the point where a client is supposed to receive +a tip, it needs to first authorize the tip. For this, the frontend must use +the :http:post:`/private/reserves/$RESERVE_PUB/authorize-tip` +API of the backend. To authorize a +tip, the frontend has to provide the following information in the body of the +POST request: + +- The amount of the tip + +- The justification (only used internally for the back-office) + +- The URL where the wallet should navigate next after the tip was + processed + +- The tip-pickup URL (see next section) + +In response to this request, the backend will return a tip token, an +expiration time and the exchange URL. The expiration time will indicate +how long the tip is valid (when the reserve expires). The tip token is +an opaque string that contains all the information needed by the wallet +to process the tip. The frontend must send this tip token to the browser +in a special “402 Payment Required” response inside the ``X-Taler-Tip`` +header. + +The frontend should handle errors returned by the backend, such as +missconfigured instances or a lack of remaining funds for tipping. + +.. _Picking-up-of-the-tip: + +Picking up of the tip +--------------------- + +The wallet will POST a JSON object to the shop’s +:http:post:`/tips/$TIP_ID/pickup` handler. +The frontend must then forward this request to the backend. The response +generated by the backend can then be forwarded directly to the wallet. + + Advanced topics =============== +.. _MerchantDatabaseScheme: + +Database Scheme +--------------- + +The merchant database must be initialized using taler-merchant-dbinit. +This tool creates the tables required by the Taler merchant to operate. +The tool also allows you to reset the Taler merchant database, which is +useful for test cases but should never be used in production. Finally, +taler-merchant-dbinit has a function to garbage collect a database, +allowing administrators to purge records that are no longer required. + +The database scheme used by the merchant looks as follows: + +.. image:: merchant-db.png + + + Configuration format -------------------- -configuration +.. index:: configuration + In Taler realm, any component obeys to the same pattern to get configuration values. According to this pattern, once the component has been installed, the installation deploys default values in @@ -835,7 +1146,7 @@ Note that, in this stage of development, the file component. For example, both an exchange and a bank can read values from it. -The repository ``git://taler.net/deployment`` contains examples of +The `deployment repository <https://git.taler.net/deployment>`_ contains examples of configuration file used in our demos. See under ``deployment/config``. **Note** @@ -847,9 +1158,10 @@ configuration file used in our demos. See under ``deployment/config``. .. _Using-taler_002dconfig: Using taler-config ------------------- +^^^^^^^^^^^^^^^^^^ + +.. index:: taler-config -taler-config The tool ``taler-config`` can be used to extract or manipulate configuration values; however, the configuration use the well-known INI file format and can also be edited by hand. @@ -888,195 +1200,66 @@ compare: :: - $ taler-config -s ACCOUNT-bank \ - -o WIRE_RESPONSE - $ taler-config -f -s ACCOUNT-bank \ - -o WIRE_RESPONSE + $ taler-config -s PATHS \ + -o TALER_DATA_HOME + $ taler-config -f -s PATHS \ + -o TALER_DATA_HOME While the configuration file is typically located at ``$HOME/.config/taler.conf``, an alternative location can be specified to ``taler-merchant-httpd`` and ``taler-config`` using the ``-c`` option. -.. _Merchant-key-management: -Merchant key management ------------------------ -merchant key -KEYFILE -The option “KEYFILE” in the section “INSTANCE-default” specifies the -path to the instance’s private key. You do not need to create a key -manually, the backend will generate it automatically if it is missing. -While generally unnecessary, it is possible to display the corresponding -public key using the ``gnunet-ecc`` command-line tool: +.. _MerchantBenchmarking: -:: +Benchmarking +------------ - $ gnunet-ecc -p \ - $(taler-config -f -s INSTANCE-default \ - -o KEYFILE) +.. index:: testing database -.. _Tipping-visitors: +NOTE: This section is dated and should be reviewed! -Tipping visitors ----------------- +FIXME: which coin denominations are needed for the benchmark? -tipping -Taler can also be used to tip Web site visitors. For example, you may be -running an online survey, and you want to reward those people that have -dutifully completed the survey. If they have installed a Taler wallet, -you can provide them with a tip for their deeds. This section describes -how to setup the Taler merchant backend for tipping. +FIXME: provide "minimum" configuration file! -There are four basic steps that must happen to tip a visitor. +FIXME: explain Postgres setup! -.. _Configure-a-reserve-and-exchange-for-tipping: -Configure a reserve and exchange for tipping -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -gnunet-ecc -reserve key -To tip users, you first need to create a reserve. A reserve is a pool of -money held in escrow at the Taler exchange. This is the source of the -funds for the tips. Tipping will fail (resulting in disappointed -visitors) if you do not have enough funds in your reserve! - -First, we configure the backend. You need to enable tipping for each -instance separately, or you can use an instance only for tipping. To -configure the “default” instance for tipping, use the following -configuration: +Setup: create Exchange account and two user accounts ``42`` and ``43`` at +the bank: :: - [INSTANCE-default] - # this is NOT the tip.priv - KEYFILE = signing_key.priv - # replace the URL with the URL of the exchange you will use - TIP_EXCHANGE = https://exchange:443/ - # here put the path to the file created with "gnunet-ecc -g1 tip.priv" - TIP_RESERVE_PRIV_FILENAME = tip.priv + $ taler-bank-manage django add_bank_account Exchange + $ taler-bank-manage django add_bank_account 42 + $ taler-bank-manage django add_bank_account 43 -Note that the KEYFILE option should have already been present for the -instance. It has nothing to do with the “tip.priv” file we created -above, and you should probably use a different file here. - -Instead of manually editing the configuration, you could also run: +Setup exchange password using: :: - $ taler-config -s INSTANCE-default \ - -o TIP_RESERVE_PRIV_FILENAME \ - -V tip.priv - $ taler-config -s INSTANCE-default \ - -o TIP_EXCHANGE \ - -V https://exchange:443/ + $ taler-bank-manage django changepassword_unsafe Exchange PASSWORD -Next, to create the ``TIP_RESERVE_PRIV_FILENAME`` file, use: +Configure merchant and exchange, then run: :: - $ gnunet-ecc -g 1 \ - $(taler-config -f -s INSTANCE-default \ - -o TIP-RESERVE_PRIV_FILENAME) - -This will create a file with the private key that will be used to -identify the reserve. You need to do this once for each instance that is -configured to tip. + $ taler-exchange-dbinit + $ taler-exchange-keyup + $ taler-merchant-dbinit -Now you can (re)start the backend with the new configuration. - -.. _Fund-the-reserve: - -Fund the reserve -~~~~~~~~~~~~~~~~ - -reserve -close -To fund the reserve, you must first extract the public key from -“tip.priv”: - -:: - - $ gnunet-ecc --print-public-key \ - $(taler-config -f -s INSTANCE-default \ - -o TIP-RESERVE_PRIV_FILENAME) - -In our example, the output for the public key is: +Launch bank, exchange and merchant backends: :: - QPE24X8PBX3BZ6E7GQ5VAVHV32FWTTCADR0TRQ183MSSJD2CHNEG - -You now need to make a wire transfer to the exchange’s bank account -using the public key as the wire transfer subject. The exchange’s bank -account details can be found in JSON format at -“https://exchange:443//wire/METHOD” where METHOD is the respective wire -method (i.e. “sepa”). Depending on the exchange’s operator, you may also -be able to find the bank details in a human-readable format on the main -page of the exchange. - -Make your wire transfer and (optionally) check at -“https://exchange:443/reserve/status/reserve_pub=QPE24X...” whether your -transfer has arrived at the exchange. - -Once the funds have arrived, you can start to use the reserve for -tipping. - -Note that an exchange will typically close a reserve after four weeks, -wiring all remaining funds back to the sender’s account. Thus, you -should plan to wire funds corresponding to a campaign of about two weeks -to the exchange initially. If your campaign runs longer, you should wire -further funds to the reserve every other week to prevent it from -expiring. - -.. _Authorize-a-tip: - -Authorize a tip -~~~~~~~~~~~~~~~ - -When your frontend has reached the point where a client is supposed to -receive a tip, it needs to first authorize the tip. For this, the -frontend must use the “/tip-authorize” API of the backend. To authorize -a tip, the frontend has to provide the following information in the body -of the POST request: - -- The amount of the tip - -- The justification (only used internally for the back-office) - -- The URL where the wallet should navigate next after the tip was - processed - -- The tip-pickup URL (see next section) - -In response to this request, the backend will return a tip token, an -expiration time and the exchange URL. The expiration time will indicate -how long the tip is valid (when the reserve expires). The tip token is -an opaque string that contains all the information needed by the wallet -to process the tip. The frontend must send this tip token to the browser -in a special “402 Payment Required” response inside the ``X-Taler-Tip`` -header. - -The frontend should handle errors returned by the backend, such as -missconfigured instances or a lack of remaining funds for tipping. - -.. _Picking-up-of-the-tip: - -Picking up of the tip -~~~~~~~~~~~~~~~~~~~~~ - -The wallet will POST a JSON object to the shop’s “/tip-pickup” handler. -The frontend must then forward this request to the backend. The response -generated by the backend can then be forwarded directly to the wallet. + $ taler-bank-manage serve-http & + $ taler-exchange-httpd & + $ taler-merchant-httpd & -.. _Generate-payments: -Generate payments ------------------ - -testing database The merchant codebase offers the ``taler-merchant-benchmark`` tool to populate the database with fake payments. This tool is in charge of starting a merchant, exchange, and bank processes, and provide them all @@ -1086,9 +1269,6 @@ own configuration (as they would do in production). The tool takes all of the values it needs from the command line, with some of them being mandatory. Among those, we have: -- ``--currency=K`` Use currency *K*, for example to craft coins to - withdraw. - - ``--bank-url=URL`` Assume that the bank is serving under the base URL *URL*. This option is only actually used by the tool to check if the bank was well launched. @@ -1144,6 +1324,183 @@ options: .. [1] https://docs.docker.com/ -.. [2] - Supporting SEPA is still work in progress; the backend will accept - this configuration, but the exchange will not work with SEPA today. + + +Diagnostics +=========== + +This chapter includes various (very unpolished) sections on specific +topics that might be helpful to understand how the exchange operates, +which files should be backed up. The information may also be helpful for +diagnostics. + +This chapter contains some legacy documentation we need to update +before it can be considered even reasonably accurate. + + +Taler payments generator +------------------------ + +This tool does not exist anymore right now... + +The tool ``taler-merchant-generate-payments`` can be used to test the +merchant backend installation. It implements all the payment’s steps in +a programmatically way, relying on the backend you give it as input. +Note that this tool gets installed along all the merchant backend’s +binaries. + +This tool gets configured by a config file, that must have the following +layout: + +:: + + [PAYMENTS-GENERATOR] + + # The exchange used during the test: make sure the merchant backend + # being tested accpets this exchange. + # If the sysadmin wants, she can also install a local exchange + # and test against it. + EXCHANGE = https://exchange.demo.taler.net/ + + # This value must indicate some URL where the backend + # to be tested is listening; it doesn't have to be the + # "official" one, though. + MERCHANT = http://localbackend/ + + # This value is used when the tool tries to withdraw coins, + # and must match the bank used by the exchange. If the test is + # done against the exchange at https://exchange.demo.taler.net/, + # then this value can be "https://bank.demo.taler.net/". + BANK = https://bank.demo.taler.net/ + + # The merchant instance in charge of serving the payment. + # Make sure this instance has a bank account at the same bank + # indicated by the 'bank' option above. + INSTANCE = default + + # The currency used during the test. Must match the one used + # by merchant backend and exchange. + CURRENCY = KUDOS + +Run the test in the following way: + +:: + + $ taler-merchant-generate-payments [-c config] [-e EURL] [-m MURL] + +The argument ``config`` given to ``-c`` points to the configuration file +and is optional – ``^/.config/taler.conf`` will be checked by default. +By default, the tool forks two processes: one for the merchant backend, +and one for the exchange. The option ``-e`` (``-m``) avoids any exchange +(merchant backend) fork, and just runs the generator against the +exchange (merchant backend) running at ``EURL`` (``MURL``). + +Please NOTE that the generator contains *hardcoded* values, as for +deposit fees of the coins it uses. In order to work against the used +exchange, those values MUST match the ones used by the exchange. + +The following example shows how the generator "sets" a deposit fee of +EUR:0.01 for the 5 EURO coin. + +:: + + // from <merchant_repository>/src/sample/generate_payments.c + { .oc = OC_PAY, + .label = "deposit-simple", + .expected_response_code = MHD_HTTP_OK, + .details.pay.contract_ref = "create-proposal-1", + .details.pay.coin_ref = "withdraw-coin-1", + .details.pay.amount_with_fee = concat_amount (currency, "5"), + .details.pay.amount_without_fee = concat_amount (currency, "4.99") }, + +The logic calculates the deposit fee according to the subtraction: +``amount_with_fee - amount_without_fee``. + +The following example shows a 5 EURO coin configuration - needed by the +used exchange - which is compatible with the hardcoded example above. + +:: + + [COIN_eur_5] + value = EUR:5 + duration_overlap = 5 minutes + duration_withdraw = 7 days + duration_spend = 2 years + duration_legal = 3 years + fee_withdraw = EUR:0.00 + fee_deposit = EUR:0.01 # important bit + fee_refresh = EUR:0.00 + fee_refund = EUR:0.00 + rsa_keysize = 1024 + +If the command terminates with no errors, then the merchant backend is +correctly installed. + +After this operation is done, the merchant database will have some dummy +data in it, so it may be convenient to clean all the tables; to this +purpose, issue the following command: + +:: + + $ taler-merchant-dbinit -r + + + + + +Legacy +====== + +Installing Taler using Docker +----------------------------- + +This section provides instructions for the merchant backend installation +using ‘Docker‘. + +For security reasons, we run Docker against a VirtualBox instance, so +the ``docker`` command should connect to a ``docker-machine`` instance +that uses the VirtualBox driver. + +Therefore, the needed tools are: “docker“, “docker-machine“, and +“docker-compose“. Please refer to Docker’s official [1]_ documentation +in order to get those components installed, as that is not in this +manual’s scope. + +Before starting to build the merchant’s image, make sure a +“docker-machine“ instance is up and running. + +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: + +:: + + $ git clone git://git.taler.net/deployment + +Now we actually build the merchant’s image. From the same directory as +above: + +:: + + $ cd deployment/docker/merchant/ + $ docker-compose build + +If everything worked as expected, the merchant is ready to be launched. +From the same directory as the previous step: + +:: + + # Recall: the docker-machine should be up and running. + $ docker-compose up + +You should see some live logging from all the involved containers. At +this stage of development, you should also ignore some (harmless) error +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: + +:: + + $ curl http://$(docker-machine ip)/ + # A greeting message should be returned by the merchant. |