path: root/texinfo/taler-merchant.texi

\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename taler-merchant.info
@documentencoding UTF-8
@ifinfo
@*Generated by Sphinx 3.4.3.@*
@end ifinfo
@settitle Taler Merchant Manual
@defindex ge
@paragraphindent 0
@exampleindent 4
@finalout
@dircategory CATEGORY
@direntry
* MENU ENTRY: (taler-merchant.info). DESCRIPTION
@end direntry

@definfoenclose strong,`,'
@definfoenclose emph,`,'
@c %**end of header

@copying
@quotation
GNU Taler 0.9.0, Jun 20, 2022

GNU Taler team

Copyright @copyright{} 2014-2022 Taler Systems SA (GPLv3+ or GFDL 1.3+)
@end quotation

@end copying

@titlepage
@title Taler Merchant Manual
@insertcopying
@end titlepage
@contents

@c %** start of user preamble

@c %** end of user preamble

@ifnottex
@node Top
@top Taler Merchant Manual
@insertcopying
@end ifnottex

@c %**start of body
@anchor{taler-merchant-manual doc}@anchor{0}
@menu
* Introduction:: 
* Terminology:: 
* Installation:: 
* How to configure the merchant’s backend:: 
* Instance setup:: 
* Secure setup:: 
* Customization:: 
* Upgrade procedure:: 
* Tipping visitors:: 
* Advanced topics:: 
* Advanced experimental features:: 
* Temporarily Abandoned Features:: 
* Index:: 

@detailmenu
 --- The Detailed Node Listing ---

Introduction

* About GNU Taler:: 
* About this manual:: 
* Architecture overview:: 

Terminology

* Instances:: 
* Accounts:: 
* Inventory:: 
* Orders and Contracts:: 
* Transfers:: 
* Tipping:: 
* Reserves:: 

Installation

* Generic instructions for installation from source:: 
* Installing the GNU Taler binary packages on Debian:: 
* Installing the GNU Taler binary packages on Trisquel:: 
* Installing the GNU Taler binary packages on Ubuntu:: 
* Installing Taler on Debian GNU/Linux from source:: 

Generic instructions for installation from source

* Installation of dependencies:: 
* Installing GNUnet:: 
* Installing the GNU Taler exchange:: 
* Installing the GNU Taler merchant backend:: 

How to configure the merchant’s backend

* Configuration format:: 
* Using taler-config:: 
* Backend options:: 
* Sample backend configuration:: 
* Launching the backend:: 

Backend options

* Service address:: 
* Currency:: 
* Database:: 
* Exchange:: 
* Auditor:: 

Instance setup

* KUDOS Accounts:: 
* IBAN Accounts:: 
* Setup:: 

Secure setup

* Using UNIX domain sockets:: 
* Reverse proxy configuration:: 
* Access control:: 
* Status code remapping:: 

Reverse proxy configuration

* Nginx:: 
* Apache:: 

Access control

* Nginx: Nginx<2>. 
* Apache: Apache<2>. 

Status code remapping

* Nginx: Nginx<3>. 
* Apache: Apache<3>. 

Customization

* Templates:: 
* Static files:: 
* Internationalization:: 
* Limitations:: 

Tipping visitors

* Fund the reserve:: 
* Authorize a tip:: 
* Picking up of the tip:: 

Advanced topics

* Database Scheme:: 
* Configuration format: Configuration format<2>. 

Configuration format

* Using taler-config: Using taler-config<2>. 

Advanced experimental features

* Benchmarking:: 
* Benchmark setup:: 
* Running the benchmark command:: 

Temporarily Abandoned Features

* Installing Taler using Docker:: 

@end detailmenu
@end menu

@node Introduction,Terminology,Top,Top
@anchor{taler-merchant-manual ffoobar}@anchor{1}@anchor{taler-merchant-manual gnu-taler-merchant-backend-operator-manual}@anchor{2}@anchor{taler-merchant-manual introduction}@anchor{3}
@chapter Introduction


@menu
* About GNU Taler:: 
* About this manual:: 
* Architecture overview:: 

@end menu

@node About GNU Taler,About this manual,,Introduction
@anchor{taler-merchant-manual about-gnu-taler}@anchor{4}
@section About GNU Taler


GNU Taler is an open protocol for an electronic payment system with a
free software reference implementation. GNU Taler offers secure, fast
and easy payment processing using well understood cryptographic
techniques. GNU Taler allows customers to remain anonymous, while
ensuring that merchants can be held accountable by governments. Hence,
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
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
offering regular currencies today.

@node About this manual,Architecture overview,About GNU Taler,Introduction
@anchor{taler-merchant-manual about-this-manual}@anchor{5}@anchor{taler-merchant-manual id1}@anchor{6}
@section About this manual


This manual targets system administrators who want to install a GNU
Taler merchant @emph{backend}.

We expect some moderate familiarity with the compilation and
installation of Free Software packages. An understanding of cryptography
is not required.

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
how to configure the backend, including in particular the configuration
of the bank account details of the merchant.

The last chapter gives some additional information about advanced topics
which will be useful for system administrators but are not necessary for
operating a basic backend.

@node Architecture overview,,About this manual,Introduction
@anchor{taler-merchant-manual architecture-overview}@anchor{7}@anchor{taler-merchant-manual id2}@anchor{8}
@section Architecture overview


@geindex crypto-currency

@geindex 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
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.

@geindex frontend

@geindex back-office

@geindex backend

@geindex DBMS

@geindex PostgreSQL

The Taler software stack for a merchant consists of four main
components:


@itemize -

@item 
A @emph{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.
The Merchant API Tutorial gives an
introduction for how to integrate Taler with Web shop frontends.

@item 
A @emph{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
not included with Taler, but rather assumed to exist at the
merchant. The Merchant Backend API provides
the API specification that should be reviewed to integrate such a
back-office with the Taler backend.

@item 
A Taler-specific payment @emph{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.

@item 
A @emph{DBMS} which stores the transaction history for the Taler backend.
For now, the GNU Taler reference implementation only supports
PostgreSQL, but the code could be easily extended to support another
DBMS.  Please review the PostgreSQL documentation for details on
how to configure the database.
@end itemize

The following image illustrates the various interactions of these key
components:

@image{taler-merchant-figures/arch-api,,,,png}

@geindex 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 are 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 @code{/private/} and @code{/management/} API endpoints of the
merchant backend. Please carefully review the section on @ref{9,,Secure setup} before deploying a Taler merchant backend to production.

@node Terminology,Installation,Introduction,Top
@anchor{taler-merchant-manual terminology}@anchor{a}
@chapter Terminology


This chapter describes some of the key concepts used throughout the manual.

@menu
* Instances:: 
* Accounts:: 
* Inventory:: 
* Orders and Contracts:: 
* Transfers:: 
* Tipping:: 
* Reserves:: 

@end menu

@node Instances,Accounts,,Terminology
@anchor{taler-merchant-manual instances}@anchor{b}
@section Instances


@geindex instance

The backend allows the user to run multiple @emph{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).

@node Accounts,Inventory,Instances,Terminology
@anchor{taler-merchant-manual accounts}@anchor{c}
@section Accounts


@geindex account

To receive payments, an instance must have configured one or more bank
@emph{accounts}.  The backend does not have accounts for users, and instances are
also not really 'accounts'. So whenever we use the term @emph{account}, it is about
a bank account of a merchant.

@node Inventory,Orders and Contracts,Accounts,Terminology
@anchor{taler-merchant-manual inventory}@anchor{d}
@section Inventory


@geindex inventory

@geindex product

@geindex lock

@geindex unit

@geindex order

The Taler backend offers inventory management as an optional function.
Inventory is tracked per instance and consists of @emph{products} sold in
@emph{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 @emph{lock} products,
reserving them for a particular (unpaid) @emph{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.

@node Orders and Contracts,Transfers,Inventory,Terminology
@anchor{taler-merchant-manual orders-and-contracts}@anchor{e}
@section Orders and Contracts


@geindex order

@geindex contract

@geindex claim

@geindex pay

@geindex refund

@geindex wire deadline

@geindex lock

@geindex 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 @emph{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.
Sharing order URLs is explicitly allowed: if a user shares an order URL
with another user, that other user should be given the opportunity to
purchase the same product.

To prevent unauthorized wallets from claiming an order, merchants can specify
that claims require authorization in the form of a @emph{claim token}. This is
useful in case the order ID is predictable (say because an existing order ID
scheme from the merchant frontend is used) and at the same time malicious
actors claiming orders is problematic (say because of limited stocks). The use
of claim tokens is optional, but if a claim token is used, it must be provided
to the wallet as part of the order URI.

Additionally, when stocks are limited, you can configure Taler to
set a @emph{product lock} on items (say, while composing the shopping cart).
These locks, as well as the @emph{order lock} (when the order is complete),
can be configured to auto-unlock at certain times.

@c FIXME: Is "can be configured" correct?  (Are there controls surfaced?)

A wallet may @emph{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 @emph{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 @emph{refund} a contract order, for example if the
contract cannot be fulfilled after all. Refunds are only possible after the
customer paid and before the exchange has @emph{wired} the payment to the
merchant. Once the funds have been wired, refunds are no longer allowed by the
Taler exchange.  The @emph{wire deadline} specifies the latest time by which an
exchange must wire the funds, while the (earlier) @emph{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 @emph{legal expiration} (by default a
decade), contract information is deleted.

@node Transfers,Tipping,Orders and Contracts,Terminology
@anchor{taler-merchant-manual transfers}@anchor{f}
@section Transfers


@geindex transfer

@geindex 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 @emph{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.

@node Tipping,Reserves,Transfers,Terminology
@anchor{taler-merchant-manual tipping}@anchor{10}
@section Tipping


@geindex tip

@geindex grant

@geindex pick up

Taler does not only allow a Website to be paid, but also to make voluntary,
non-contractual payments to visitors, called @emph{tips}.  Such tips could be
granted as a reward for filling in surveys or watching advertizements. 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 @emph{grant} tips, allowing wallets to @emph{pick up}
the tip.

@node Reserves,,Tipping,Terminology
@anchor{taler-merchant-manual reserves}@anchor{11}
@section Reserves


@geindex reserve

@geindex close

A @emph{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 @emph{close} a reserve after a fixed period of time
(typically about a month), wiring any remaining funds back to the merchant.

@node Installation,How to configure the merchant’s backend,Terminology,Top
@anchor{taler-merchant-manual installation}@anchor{12}
@chapter Installation


This chapter describes how to install the GNU Taler merchant backend.

@menu
* Generic instructions for installation from source:: 
* Installing the GNU Taler binary packages on Debian:: 
* Installing the GNU Taler binary packages on Trisquel:: 
* Installing the GNU Taler binary packages on Ubuntu:: 
* Installing Taler on Debian GNU/Linux from source:: 

@end menu

@node Generic instructions for installation from source,Installing the GNU Taler binary packages on Debian,,Installation
@anchor{taler-merchant-manual generic-instructions}@anchor{13}@anchor{taler-merchant-manual generic-instructions-for-installation-from-source}@anchor{14}
@section Generic instructions for installation from source


This section provides generic instructions for the merchant backend
installation independent of any particular operating system. Operating
system specific instructions are provided in the following sections. You
should follow the operating system specific instructions if those are
available, and only consult the generic instructions if no
system-specific instructions are provided for your specific operating
system.

@menu
* Installation of dependencies:: 
* Installing GNUnet:: 
* Installing the GNU Taler exchange:: 
* Installing the GNU Taler merchant backend:: 

@end menu

@node Installation of dependencies,Installing GNUnet,,Generic instructions for installation from source
@anchor{taler-merchant-manual id3}@anchor{15}@anchor{taler-merchant-manual installation-of-dependencies}@anchor{16}
@subsection Installation of dependencies


The following packages need to be installed before we can compile the
backend:


@itemize -

@item 
libsqlite3 >= 3.16.2

@item 
GNU libunistring >= 0.9.3

@item 
libcurl >= 7.26 (or libgnurl >= 7.26)

@item 
libqrencode >= 4.0.0

@item 
GNU libgcrypt >= 1.6

@item 
libsodium >= 1.0

@item 
libargon2 >= 20171227

@item 
libjansson >= 2.7

@item 
PostgreSQL >= 13, including libpq

@item 
GNU libmicrohttpd >= 0.9.71

@item 
GNUnet >= 0.16 (from source tarball@footnote{http://ftpmirror.gnu.org/gnunet/})

@item 
GNU Taler exchange (see release announcement@footnote{https://mail.gnu.org/archive/cgi-bin/namazu.cgi?query=taler&idxname=info-gnu&max=20&result=normal&sort=date:late})
@end itemize

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@footnote{http://ftpmirror.gnu.org/taler/},
you might as well also download the tarball for GNU Taler merchant.

GNU Taler components version numbers follow the @code{MAJOR.MINOR.MICRO} format.
The general rule for compatibility is that @code{MAJOR} and @code{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 @code{libgnunetutil} and GNU Taler exchange dependencies.

@node Installing GNUnet,Installing the GNU Taler exchange,Installation of dependencies,Generic instructions for installation from source
@anchor{taler-merchant-manual installing-gnunet}@anchor{17}@anchor{taler-merchant-manual installing-libgnunetutil}@anchor{18}
@subsection Installing GNUnet


@geindex GNUnet

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 install GNUnet, unpack the tarball and change
into the resulting directory, then proceed as follows:

@example
$ ./configure [--prefix=GNUNETPFX]
$ # Each dependency can be fetched from non standard locations via
$ # the '--with-<LIBNAME>' option. See './configure --help'.
$ make
# make install
# ldconfig
@end example

If you did not specify a prefix, GNUnet will install to @code{/usr/local},
which requires you to run the last step as @code{root}.
The @code{ldconfig} command (also run as @code{root}) makes the
shared object libraries (@code{.so} files)
visible to the various installed programs.

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!

@node Installing the GNU Taler exchange,Installing the GNU Taler merchant backend,Installing GNUnet,Generic instructions for installation from source
@anchor{taler-merchant-manual id4}@anchor{19}@anchor{taler-merchant-manual installing-the-gnu-taler-exchange}@anchor{1a}
@subsection Installing the GNU Taler exchange


@geindex exchange

After installing GNUnet, unpack the GNU Taler exchange tarball,
change into the resulting directory, and proceed as follows:

@example
$ ./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
@end example

If you did not specify a prefix, the exchange will install to @code{/usr/local},
which requires you to run the last step as @code{root}.  You have to specify
@code{--with-gnunet=/usr/local} if you installed GNUnet to @code{/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!

@node Installing the GNU Taler merchant backend,,Installing the GNU Taler exchange,Generic instructions for installation from source
@anchor{taler-merchant-manual id5}@anchor{1b}@anchor{taler-merchant-manual installing-the-gnu-taler-merchant-backend}@anchor{1c}
@subsection Installing the GNU Taler merchant backend


@geindex backend

GNU Taler merchant has these additional dependencies:


@itemize -

@item 
libqrencode >= 4.0.0
@end itemize

The following steps assume all dependencies are installed.

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:

@example
$ ./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
@end example

If you did not specify a prefix, the exchange will install to
@code{/usr/local}, which requires you to run the last step as @code{root}.

You have to specify @code{--with-exchange=/usr/local} and/or
@code{--with-gnunet=/usr/local} if you installed the exchange and/or
GNUnet to @code{/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 @code{/etc/ld.so.conf}, adding
lines for @code{GNUNETPFX/lib/} and @code{EXCHANGEPFX/lib/} and @code{PFX/lib/}
(replace the prefixes with the actual paths you used). Afterwards, you should
run @code{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.

Please note that unlike most packages, if you want to run the @code{make check}
command, you should run it only @emph{after} having done @code{make install}.  The
latter ensures that necessary binaries are copied to the right place.

Gratuitous editorial note by TTN: I think this is a quirk that we should
fix in the long-term as such weirdness might hide other build issues.
However, this is probably a minority viewpoint.

In any case, if @code{make check} fails, please consider filing a
bug report with the Taler bug tracker@footnote{https://bugs.taler.net}.

@node Installing the GNU Taler binary packages on Debian,Installing the GNU Taler binary packages on Trisquel,Generic instructions for installation from source,Installation
@anchor{taler-merchant-manual installing-the-gnu-taler-binary-packages-on-debian}@anchor{1d}
@section Installing the GNU Taler binary packages on Debian


To install the GNU Taler Debian packages, first ensure that you have
the right Debian distribution. At this time, the packages are built for
Bullseye.

You need to add a file to import the GNU Taler packages. Typically,
this is done by adding a file @code{/etc/apt/sources.list.d/taler.list} that
looks like this:

@example
deb https://deb.taler.net/apt/debian bullseye main
@end example

Next, you must import the Taler Systems SA public package signing key
into your keyring and update the package lists:

@example
# wget -O - https://taler.net/taler-systems.gpg.key | apt-key add -
# apt update
@end example

@cartouche
@quotation Note 
You may want to verify the correctness of the Taler Systems key out-of-band.
@end quotation
@end cartouche

Now your system is ready to install the official GNU Taler binary packages
using apt.

To install the Taler merchant backend, you can now simply run:

@example
# apt install taler-merchant
@end example

Note that the package does not complete the integration of the backend with
the HTTP reverse proxy (typically with TLS certificates).  A configuration
fragment for Nginx or Apache will be placed in
@code{/etc/@{apache,nginx@}/conf-available/taler-merchant.conf}.  You must
furthermore still configure the instances, and may need to extend the fragment
with access control restrictions for non-default instances.

@node Installing the GNU Taler binary packages on Trisquel,Installing the GNU Taler binary packages on Ubuntu,Installing the GNU Taler binary packages on Debian,Installation
@anchor{taler-merchant-manual installing-the-gnu-taler-binary-packages-on-trisquel}@anchor{1e}
@section Installing the GNU Taler binary packages on Trisquel


To install the GNU Taler Trisquel packages, first ensure that you have
the right Trisquel distribution. Packages are currently available for
Trisquel GNU/Linux 10.0.  Simply follow the same instructions provided
for Ubuntu 20.04 LTS (Focal Fossa).

@node Installing the GNU Taler binary packages on Ubuntu,Installing Taler on Debian GNU/Linux from source,Installing the GNU Taler binary packages on Trisquel,Installation
@anchor{taler-merchant-manual installing-the-gnu-taler-binary-packages-on-ubuntu}@anchor{1f}
@section Installing the GNU Taler binary packages on Ubuntu


To install the GNU Taler Ubuntu packages, first ensure that you have
the right Ubuntu distribution. At this time, the packages are built for
Ubuntu 20.04 LTS (Focal Fossa).

A typical @code{/etc/apt/sources.list.d/taler.list} file for this setup
would look like this:

@example
deb https://deb.taler.net/apt/ubuntu/ focal-fossa main
@end example

The last line is crucial, as it adds the GNU Taler packages.

Next, you must import the Taler Systems SA public package signing key
into your keyring and update the package lists:

@example
# wget -O - https://taler.net/taler-systems.gpg.key | apt-key add -
# apt update
@end example

@cartouche
@quotation Note 
You may want to verify the correctness of the Taler Systems key out-of-band.
@end quotation
@end cartouche

Now your system is ready to install the official GNU Taler binary packages
using apt.

To install the Taler merchant backend, you can now simply run:

@example
# apt install taler-merchant
@end example

Note that the package does not complete the integration of the backend with
the HTTP reverse proxy (typically with TLS certificates).  A configuration
fragment for Nginx or Apache will be placed in
@code{/etc/@{apache,nginx@}/conf-available/taler-merchant.conf}.  You must
furthermore still configure the instances, and may need to extend the fragment
with access control restrictions for non-default instances.

@node Installing Taler on Debian GNU/Linux from source,,Installing the GNU Taler binary packages on Ubuntu,Installation
@anchor{taler-merchant-manual installing-taler-on-debian-gnu-002flinux}@anchor{20}@anchor{taler-merchant-manual installing-taler-on-debian-gnu-linux-from-source}@anchor{21}
@section Installing Taler on Debian GNU/Linux from source


@geindex Wheezy

@geindex Jessie

@geindex Stretch

@geindex Buster

@geindex Bullseye

@geindex Debian

Debian Wheezy is too old and lacks most of the packages required.
Debian Jessie, Stretch, and Buster are better, but still lack PostgreSQL 12.

@cartouche
@quotation Note 
When compiling PostgreSQL 12, make sure to
do @code{make world} to build the @code{contrib/} modules, and
@code{cd contrib && make install} to install them, as well.
@end quotation
@end cartouche

On Debian Stretch and Buster, only GNU libmicrohttpd needs to be compiled from
source. To install dependencies on Debian Stretch, run the following
commands:

@example
# apt-get install \
  libqrencode-dev \
  libsqlite3-dev \
  libltdl-dev \
  libunistring-dev \
  libsodium-dev \
  libargon2-0-dev \
  libcurl4-gnutls-dev \
  libgcrypt20-dev \
  libjansson-dev \
  libpq-dev \
  postgresql-9.6
# wget https://ftpmirror.gnu.org/libmicrohttpd/libmicrohttpd-latest.tar.gz
# wget https://ftpmirror.gnu.org/libmicrohttpd/libmicrohttpd-latest.tar.gz.sig
# gpg -v libmicrohttpd-latest.tar.gz # Should show signed by 939E6BE1E29FC3CC
# tar xf libmicrohttpd-latest.tar.gz
# cd libmicrohttpd-0*
# ./configure
# make install
@end example

For more recent versions of Debian, you should instead run:

@example
# apt-get install \
  libqrencode-dev \
  libsqlite3-dev \
  libltdl-dev \
  libunistring-dev \
  libsodium-dev \
  libargon2-dev \
  libcurl4-gnutls-dev \
  libgcrypt20-dev \
  libjansson-dev \
  libpq-dev \
  postgresql-9.6 \
  libmicrohttpd-dev
@end example

Note that Stretch requires @code{libargon2-0-dev},
while later versions of Debian require @code{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 Stretch instructions above, you need to pass
@code{--with-microhttpd=/usr/local/} to all @code{configure} invocations.

@node How to configure the merchant’s backend,Instance setup,Installation,Top
@anchor{taler-merchant-manual how-to-configure-the-merchants-backend}@anchor{22}
@chapter How to configure the merchant’s backend


@geindex taler-config

@geindex 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
default, the file @code{$HOME/.config/taler.conf} is where the Web shop
administrator specifies configuration values that augment or override
the defaults. The format of the configuration file is the well-known INI
file format. You can edit the file by hand, or use the @code{taler-config}
commands given as examples.

@menu
* Configuration format:: 
* Using taler-config:: 
* Backend options:: 
* Sample backend configuration:: 
* Launching the backend:: 

@end menu

@node Configuration format,Using taler-config,,How to configure the merchant’s backend
@anchor{taler-merchant-manual configuration-format}@anchor{23}
@section Configuration format


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
$@{prefix@}/share/taler/config.d/, in .conf files. In order to override
these defaults, the user can write a custom .conf file and either pass
it to the component at execution time, or name it taler.conf and place
it under $HOME/.config/.

A config file is a text file containing sections, and each section
contains its values. The right format follows:

@example
[section1]
value1 = string
value2 = 23

[section2]
value21 = string
value22 = /path22
@end example

Throughout any configuration file, it is possible to use @code{$}-prefixed
variables, like @code{$VAR}, especially when they represent filesystem
paths. It is also possible to provide defaults values for those
variables that are unset, by using the following syntax:
@code{$@{VAR:-default@}}. However, there are two ways a user can set
@code{$}-prefixable variables:

by defining them under a @code{[paths]} section, see example below,

@example
[paths]
TALER_DEPLOYMENT_SHARED = $@{HOME@}/shared-data
..
[section-x]
path-x = $@{TALER_DEPLOYMENT_SHARED@}/x
@end example

or by setting them in the environment:

@example
$ export VAR=/x
@end example

The configuration loader will give precedence to variables set under
@code{[path]}, though.

The utility @code{taler-config}, which gets installed along with the
exchange, serves to get and set configuration values without directly
editing the .conf. The option @code{-f} is particularly useful to resolve
pathnames, when they use several levels of @code{$}-expanded variables. See
@code{taler-config --help}.

Note that, in this stage of development, the file
@code{$HOME/.config/taler.conf} can contain sections for @emph{all} the
component. For example, both an exchange and a bank can read values from
it.

The repository @code{git://taler.net/deployment} contains examples of
configuration file used in our demos. See under @code{deployment/config}.

@quotation

@strong{Note}

Expectably, some components will not work just by using default
values, as their work is often interdependent. For example, a
merchant needs to know an exchange URL, or a database name.
@end quotation

@node Using taler-config,Backend options,Configuration format,How to configure the merchant’s backend
@anchor{taler-merchant-manual using-taler-config}@anchor{24}
@section Using taler-config


The tool @code{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.

Run

@example
$ taler-config -s $SECTION
@end example

to list all of the configuration values in section @code{$SECTION}.

Run

@example
$ taler-config -s $section -o $option
@end example

to extract the respective configuration value for option @code{$option} in
section @code{$section}.

Finally, to change a setting, run

@example
$ taler-config -s $section -o $option -V $value
@end example

to set the respective configuration value to @code{$value}. Note that you
have to manually restart the Taler backend after you change the
configuration to make the new configuration go into effect.

Some default options will use $-variables, such as @code{$DATADIR} within
their value. To expand the @code{$DATADIR} or other $-variables in the
configuration, pass the @code{-f} option to @code{taler-config}. For example,
compare:

@example
$ taler-config -s ACCOUNT-bank \
               -o WIRE_RESPONSE
$ taler-config -f -s ACCOUNT-bank \
               -o WIRE_RESPONSE
@end example

While the configuration file is typically located at
@code{$HOME/.config/taler.conf}, an alternative location can be specified
to @code{taler-merchant-httpd} and @code{taler-config} using the @code{-c}
option.

@node Backend options,Sample backend configuration,Using taler-config,How to configure the merchant’s backend
@anchor{taler-merchant-manual backend-options}@anchor{25}@anchor{taler-merchant-manual id6}@anchor{26}
@section Backend options


@geindex DBMS

@geindex PostgreSQL

@geindex UNIX domain socket

@geindex TCP

@geindex port

@geindex currency

@geindex KUDOS

@geindex exchange

@geindex instance

@geindex wire format

The following table describes the options that commonly need to be
modified. Here, the notation @code{[$section]/$option} denotes the option
@code{$option} under the section @code{[$section]} in the configuration file.

@menu
* Service address:: 
* Currency:: 
* Database:: 
* Exchange:: 
* Auditor:: 

@end menu

@node Service address,Currency,,Backend options
@anchor{taler-merchant-manual service-address}@anchor{27}
@subsection Service address


The following option sets the transport layer address used by the
merchant backend:

@example
[MERCHANT]/SERVE = TCP | UNIX
@end example

If given,


@itemize -

@item 
@code{TCP}, then we need to set the TCP port in @code{[MERCHANT]/PORT}

@item 
@code{UNIX}, then we need to set the unix domain socket path and mode
in @code{[MERCHANT]/UNIXPATH} and @code{[MERCHANT]/UNIXPATH_MODE}. The
latter takes the usual permission mask given as a number, e.g. 660
for user/group read-write access.
@end itemize

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.

To run the Taler backend on TCP port 8888, use:

@example
$ taler-config -s MERCHANT -o SERVE -V TCP
$ taler-config -s MERCHANT -o PORT -V 8888
@end example

@cartouche
@quotation Note 
When using the Debian/Ubuntu packages, these options are already
configured in the @code{/etc/taler/conf.d/merchant.conf} configuration file.

If you need to change them, you should edit @code{/etc/taler/merchant-overrides.conf},
for example by passing @code{-c /etc/taler/merchant-overrides.conf} to the
@code{taler-config} commands above.  By default, the Taler merchant
package when installed on Debian/Ubuntu will use a UNIX domain socket
at @code{/run/taler/merchant-httpd/merchant-http.sock}. For the best possible
security, it is recommended to leave this in place and configure a reverse
proxy (nginx or Apache) as described below.
@end quotation
@end cartouche

@node Currency,Database,Service address,Backend options
@anchor{taler-merchant-manual currency}@anchor{28}
@subsection Currency


Which currency the Web shop deals in, i.e. “EUR” or “USD”, is
specified using the option

@example
[TALER]/CURRENCY
@end example

For testing purposes, the currency MUST match “KUDOS” so that tests
will work with the Taler demonstration exchange at
@indicateurl{https://exchange.demo.taler.net/}:

@example
$ taler-config -s TALER -o CURRENCY -V KUDOS
@end example

@cartouche
@quotation Note 
When using the Debian/Ubuntu packages, these options should be
configured in the @code{/etc/taler/taler.conf} configuration file
(alternatively, you can also edit @code{/etc/taler/merchant-overrides.conf}).
However, you must edit the @code{taler.conf} file manually and @strong{must not}
use @code{taler-config} to do this, as that would inline the include
directives and destroy the carefully setup path structure.
@end quotation
@end cartouche

@node Database,Exchange,Currency,Backend options
@anchor{taler-merchant-manual database}@anchor{29}
@subsection Database


In principle it is possible for the backend to support different DBMSs.
The option

@example
[MERCHANT]/DB
@end example

specifies which DBMS is to be used. However, currently only the value
@code{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.

@cartouche
@quotation Note 
When using the Debian/Ubuntu packages, the database should already
be configured in the @code{/etc/taler/secrets/merchant-db.secret.conf}
configuration file.  The @code{talermerchant} database is also already
configured (unless you answered @code{no} when asked the question during
installation), so you can skip everything in this section.
@end quotation
@end cartouche

For the @code{postgres} backend, you need to provide:

@example
[MERCHANTDB-postgres]/CONFIG
@end example

This option specifies a postgres access path using the format
@code{postgres:///$DBNAME}, where @code{$DBNAME} is the name of the
PostgreSQL database you want to use. Suppose @code{$USER} is the name of
the user who will run the backend process. Then, you need to first
run:

@example
$ sudo -u postgres createuser -d $USER
@end example

as the PostgreSQL database administrator (usually @code{postgres}) to
grant @code{$USER} the ability to create new databases. Next, you should
as @code{$USER} run:

@example
$ createdb $DBNAME
@end example

to create the backend’s database. Here, @code{$DBNAME} must match the
database name given in the configuration file.

To configure the Taler backend to use this database, run:

@example
$ taler-config -s MERCHANTDB-postgres -o CONFIG \
    -V postgres:///$DBNAME
@end example

Now you should create the tables and indices. To do this, run as @code{$USER}:

@example
$ taler-merchant-dbinit
@end example

You can improve your security posture if you now REVOKE the rights to CREATE,
DROP or ALTER tables from @code{$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 PostgreSQL documentation.

Commands, like @code{taler-merchant-dbinit}, that support the @code{-l LOGFILE}
command-line option, send logging output to standard error by default.
See manpages/taler-merchant-dbinit.1 for more information.

@cartouche
@quotation Note 
The Taler merchant backend stores private keys and other sensitive
business and customer data in the database.  The backend operator
SHOULD ensure that backup operations are encrypted and secured from
unauthorized access.
@end quotation
@end cartouche

@c index: MASTER_KEY

@node Exchange,Auditor,Database,Backend options
@anchor{taler-merchant-manual exchange}@anchor{2a}
@subsection Exchange


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:


@itemize -

@item 
The @code{EXCHANGE_BASE_URL} option specifies the exchange’s base URL.
For example, to use the Taler demonstrator, specify:

@example
$ taler-config -s MERCHANT-EXCHANGE-demo \
    -o EXCHANGE_BASE_URL \
    -V https://exchange.demo.taler.net/
@end example

@item 
The @code{MASTER_KEY} option specifies the exchange’s master public key
in base32 encoding. For the Taler demonstrator, use:

@example
$ taler-config -s MERCHANT-EXCHANGE-demo \
    -o MASTER_KEY \
    -V FH1Y8ZMHCTPQ0YFSZECDH8C9407JR3YN0MF1706PTG24Q4NEWGV0
@end example

@item 
The @code{CURRENCY} option specifies the exchange’s currency.
For the Taler demonstrator, use:

@example
$ taler-config -s MERCHANT-EXCHANGE-demo \
    -o CURRENCY \
    -V KUDOS
@end example
@end itemize

Note that multiple exchanges can be added to the system by using different
tokens in place of @code{demo} in the examples above. Note that all of the
exchanges must use the same currency: If the currency does not match the main
currency from the @code{TALER} section, the exchange is ignored. If you need to
support multiple currencies, you need to configure a backend per currency.

@cartouche
@quotation Note 
Manually setting up exchanges is only recommended under special
circumstances. In general, GNU Taler will include trustworthy
auditors (for each currency) in the default configuration, and
there is rarely a good reason for trusting an exchange without
an accredited auditor.
@end quotation
@end cartouche

@node Auditor,,Exchange,Backend options
@anchor{taler-merchant-manual auditor}@anchor{2b}
@subsection Auditor


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
4that section, the following options need to be configured:


@itemize -

@item 
The @code{AUDITOR_BASE_URL} option specifies the auditor’s base URL.
For example, to use the Taler demonstrator's auditor, specify:

@example
$ taler-config -s MERCHANT-AUDITOR-demo \
    -o AUDITOR_BASE_URL \
    -V https://exchange.demo.taler.net/
@end example

@item 
The @code{AUDITOR_KEY} option specifies the auditor's public key
in base32 encoding. For the Taler demonstrator, use:

@example
$ taler-config -s MERCHANT-AUDITOR-demo \
    -o AUDITOR_KEY \
    -V DSDASDXAMDAARMNAD53ZA4AFAHA2QADAMAHHASWDAWXN84SDAA11
@end example

@item 
The @code{CURRENCY} option specifies the auditor’s currency.
For the Taler demonstrator, use:

@example
$ taler-config -s MERCHANT-AUDITOR-demo \
    -o CURRENCY \
    -V KUDOS
@end example
@end itemize

Note that multiple auditors can be added to the system by using different
tokens in place of @code{demo} in the examples above. Note that all of the
auditors must use the same currency: If the currency does not match the main
currency from the @code{TALER} section, the auditor is ignored.  If you need to
support multiple currencies, you need to configure a backend per currency.

@cartouche
@quotation Note 
Manually adding auditors is only recommended under special
circumstances. In general, GNU Taler will include trustworthy
auditors (for each currency) in the default configuration, and
there is rarely a good reason for adding an auditor that is
not coordinating its activities with the Taler developers.
@end quotation
@end cartouche

@node Sample backend configuration,Launching the backend,Backend options,How to configure the merchant’s backend
@anchor{taler-merchant-manual id7}@anchor{2c}@anchor{taler-merchant-manual sample-backend-configuration}@anchor{2d}
@section Sample backend configuration


@geindex configuration

The following is an example for a complete backend configuration:

@example
[TALER]
CURRENCY = KUDOS

[MERCHANT]
SERVE = TCP
PORT = 8888
DATABASE = postgres

[MERCHANTDB-postgres]
CONFIG = postgres:///donations

[merchant-exchange-NAME]
EXCHANGE_BASE_URL = https://exchange.demo.taler.net/
MASTER_KEY = FH1Y8ZMHCTPQ0YFSZECDH8C9407JR3YN0MF1706PTG24Q4NEWGV0
# 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
@end example

Given the above configuration, the backend will use a database named
@code{donations} within PostgreSQL.

The backend will deposit the coins it receives to the exchange at
@indicateurl{https://exchange.demo.taler.net/}, which has the master key
@code{FH1Y8ZMHCTPQ0YFSZECDH8C9407JR3YN0MF1706PTG24Q4NEWGV0}.

Please note that @code{doc/config.sh} will walk you through all
configuration steps, showing how to invoke @code{taler-config} for each of
them.

@node Launching the backend,,Sample backend configuration,How to configure the merchant’s backend
@anchor{taler-merchant-manual id8}@anchor{2e}@anchor{taler-merchant-manual launching-the-backend}@anchor{2f}
@section Launching the backend


@geindex backend

@geindex taler-merchant-httpd

Assuming you have configured everything correctly, you can launch the
merchant backend as @code{$USER} using

@example
$ taler-merchant-httpd
@end example

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.

@cartouche
@quotation Note 
When using the Debian/Ubuntu packages, the systemd configuration
will already exist. You only need to enable and start the service
using @code{systemctl enable taler-merchant-httpd} and
@code{systemctl start taler-merchant-httpd}. Additionally, you should
review the @code{/etc/apache2/sites-available/taler-merchant.conf}
or @code{/etc/nginx/sites-available/taler-merchant} (these files
contain additional instructions to follow), symlink it to
@code{sites-enabled/} and restart your HTTP server. After that, you
should be able to visit the merchant backend at the respective
HTTP(S) endpoint.
@end quotation
@end cartouche

If everything worked as expected, the command

@example
$ wget -O - http://localhost:8888/config
@end example

should return some basic configuration status data about the service.

Please note that your backend is right now likely globally reachable.  You can either:

@quotation


@itemize *

@item 
Use the @code{--auth=$TOKEN} command-line option to set an access token to be provided in an @code{Authorize: Bearer $TOKEN} HTTP header. Note that this can be used at anytime to override access control, but remains only in effect until a first instance is created or an existing instance authentication setting is modified.

@item 
Set the @code{TALER_MERCHANT_TOKEN} environment variable to @code{$TOKEN} for the same effect. This method has the advantage of @code{$TOKEN} not being visible as a command-line interface to other local users on the same machine.

@item 
Set up an instance with an authentication token before some unauthorized person has a chance to access the backend.  As the backend is useless without any instance and the chances of remote attackers during the initial configuration is low, this is probably sufficient for most use-cases. Still, keep the first two scenarios in mind in case you ever forget your access token!
@end itemize
@end quotation

Production systems should additionally be configured to bind to a UNIX domain socket
and use TLS for improved network privacy, see @ref{9,,Secure setup}.

@geindex instance

@node Instance setup,Secure setup,How to configure the merchant’s backend,Top
@anchor{taler-merchant-manual id9}@anchor{30}@anchor{taler-merchant-manual instance-setup}@anchor{31}
@chapter Instance setup


First of all, we recommend the use of the single-page administration
application that is served by default at the base URL of the merchant backend.
You can use it to perform all steps described in this section (and more!),
using a simple Web interface instead of the @code{wget} commands given below.

The first step for using the backend involves the creation of a @code{default}
instance. The @code{default} instance can also create / delete / configure other
instances, similar to the @code{root} account on UNIX.  When no instance exists
and @code{taler-merchant-httpd} was started without the @code{--auth} option, then
the backend is reachable without any access control (unless you configured
some in the reverse proxy).

The following documentation shows how to handle any instance. Thus, if you
want to have multiple instances, you may need to perform the steps multiple
times, once for each instance.

@cartouche
@quotation Note 
A security concern is that normal API usage leaks instance existence.
This means unauthorized users can distinguish between the case where the
instance does not exist (HTTP 404) and the case where access is denied
(HTTP 403).
This is all moot behind a properly configured
@ref{32,,reverse proxy}.
@end quotation
@end cartouche

@menu
* KUDOS Accounts:: 
* IBAN Accounts:: 
* Setup:: 

@end menu

@node KUDOS Accounts,IBAN Accounts,,Instance setup
@anchor{taler-merchant-manual kudos-accounts}@anchor{33}
@section 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 @code{payto://}-URI.
See RFC 8905@footnote{https://tools.ietf.org/html/rfc8905}
for the format of @code{payto://}-URIs.

For first tests, you should sign up for a KUDOS bank
account at @indicateurl{https://bank.demo.taler.net/}.
In this case, the @code{payto://}-URI will be of the form
@code{payto://x-taler-bank/bank.demo.taler.net/$USERNAME} where @code{$USERNAME}
must be replaced with the name of the account that was established
at @indicateurl{https://bank.demo.taler.net/}.

@node IBAN Accounts,Setup,KUDOS Accounts,Instance setup
@anchor{taler-merchant-manual iban-accounts}@anchor{34}
@section 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 @code{payto://}-URI of your real bank
account. In Europe, this will involve knowing your IBAN number. If you have an
IBAN, the corresponding @code{payto://}-URI is simply @code{payto://iban/$IBAN} where
@code{$IBAN} must be replaced with the actual IBAN number.

@node Setup,,IBAN Accounts,Instance setup
@anchor{taler-merchant-manual setup}@anchor{35}
@section Setup


With the knowledge of the @code{payto://}-URI, instances can be configured by POSTing
a request to @code{/management/instances}.  To create a first instance,
create a file @code{instance.json} with an InstanceConfigurationMessage

@example
@{
  "payto_uris" : [ "$PAYTO_URI" ],
  "id" : "default",
  "name": "example.com",
  "address": @{ "country" : "zz" @},
  "auth": @{ "method" : "external"@} ,
  "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 @}
@}
@end example

In the text above, you must replace @code{$PAYTO_URI} with your actual
@code{payto://}-URI. Also, be sure to replace @code{KUDOS} with the fiat currency if the
setup is for an actual bank. The @code{name} field will be shown as the name of
your shop. The @code{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 contract terms specification.

You can then create the instance using:

@example
$ wget --post-file=instance.json http://localhost:8888/management/instances
@end example

The base URL for the instance will then be
@code{http://localhost:8888/instances/default}.  You can create additional
instances by changing the @code{id} value to identifies other than @code{default}.

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 Merchant Backend API documentation.

@node Secure setup,Customization,Instance setup,Top
@anchor{taler-merchant-manual id11}@anchor{36}@anchor{taler-merchant-manual secure-setup}@anchor{9}
@chapter Secure setup


@geindex security

@geindex TLS

The Taler backend does not include even the most basic forms of
access control or transport layer security.  Thus, production
setups @strong{must} deploy the Taler backend behind an HTTP(S) server
that acts as a @emph{reverse proxy}, performs TLS termination and
authentication and then forwards requests to the backend.

@menu
* Using UNIX domain sockets:: 
* Reverse proxy configuration:: 
* Access control:: 
* Status code remapping:: 

@end menu

@node Using UNIX domain sockets,Reverse proxy configuration,,Secure setup
@anchor{taler-merchant-manual using-unix-domain-sockets}@anchor{37}
@section Using UNIX domain sockets


To ensure that the merchant backend is not exposed directly to the network,
you @emph{should} bind the backend to a UNIX domain socket:

@example
$ taler-config -s MERCHANT -o SERVE -V UNIX
$ taler-config -s MERCHANT -o UNIXPATH -V /some/path/here.sock
@end example

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
sockets created by other users/processes in "/tmp".

If UNIX domain sockets are for some reason not possible, you @emph{may} use a
host-based firewall to block access to the TCP port of the merchant backend,
but this is @emph{not recommended}.  Relying on NAT or network firewalls for access
control is gross negligence.

@node Reverse proxy configuration,Access control,Using UNIX domain sockets,Secure setup
@anchor{taler-merchant-manual id12}@anchor{38}@anchor{taler-merchant-manual reverse-proxy-configuration}@anchor{32}
@section Reverse proxy configuration


@menu
* Nginx:: 
* Apache:: 

@end menu

@node Nginx,Apache,,Reverse proxy configuration
@anchor{taler-merchant-manual nginx}@anchor{39}
@subsection Nginx


For Nginx, a possible basic reverse proxy configuration would be:

@example
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";
@end example

Note that the above assumes your domain name is @code{example.com} and that you
have TLS configured.  Leave out the last line if your Nginx reverse proxy does
not have HTTPS enabled.  Make sure to restart the @code{taler-merchant-httpd}
process after changing the @code{SERVE} configuration.

@node Apache,,Nginx,Reverse proxy configuration
@anchor{taler-merchant-manual apache}@anchor{3a}
@subsection Apache


In Apache, make sure you have @code{mod_proxy}, @code{mod_proxy_http} and
@code{mod_headers} enabled:

@example
$ a2enmod proxy
$ a2enmod proxy_http
$ a2enmod headers
@end example

Then configure your Apache reverse proxy like this (you may change the
endpoint):

@example
<Location "/">
ProxyPass "unix:/some/path/here.sock|http://example.com/"
RequestHeader add "X-Forwarded-Proto" "https"
</Location>
@end example

Note that the above again assumes your domain name is @code{example.com} and that
you have TLS configured.  Note that you must add the @code{https} header unless
your site is not available via TLS.

The above configurations are both incomplete. You must still additionally
set up access control!

@node Access control,Status code remapping,Reverse proxy configuration,Secure setup
@anchor{taler-merchant-manual access-control}@anchor{3b}
@section Access control


All endpoints with @code{/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 @code{$BASE_URL/private/} and
@code{$BASE_URL/management/} to the authorized users of the default instance, and
to @code{$BASE_URL/instances/$ID/private/} to the authorized users of the instance
@code{$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 @code{/private/} or @code{/management/})
are expected to be fully exposed to the Internet, and wallets may have to
interact with those endpoints directly without client authentication.

@menu
* Nginx: Nginx<2>. 
* Apache: Apache<2>. 

@end menu

@node Nginx<2>,Apache<2>,,Access control
@anchor{taler-merchant-manual id13}@anchor{3c}
@subsection Nginx


For Nginx, you can implement token-based merchant backend authentication as
follows:

@example
location ~ /private/ @{
    if ($http_authorization !~ "(?i)ApiKey SECURITYTOKEN") @{
       return 401;
    @}
    proxy_pass ...; # as above
@}
location /management/ @{
    if ($http_authorization !~ "(?i)ApiKey SECURITYTOKEN") @{
       return 401;
    @}
    proxy_pass ...; # as above
@}
@end example

Here, @code{SECURITYTOKEN} should be replaced with the actual shared secret.  Note
that the @code{~} ensures that the above matches all endpoints that include the
string @code{/private/}.  If you only run a single instance, you could simply
specify @code{/private/} without the @code{~} to only configure the access policy for
the default instance.

If you are running different instances on the same backend, you
likely will want to specify different access control tokens for
each instance:

@example
location ~ ^/instances/foo/private/ @{
    if ($http_authorization !~ "(?i)ApiKey FOOTOKEN") @{
       return 401;
    @}
    proxy_pass ...; # as above
@}
location ~ ^/instances/bar/private/ @{
    if ($http_authorization !~ "(?i)ApiKey BARTOKEN") @{
       return 401;
    @}
    proxy_pass ...; # as above
@}
location /private/ @{
    if ($http_authorization !~ "(?i)ApiKey MASTERTOKEN") @{
       return 401;
    @}
    proxy_pass ...; # as above
@}
location /management/ @{
    if ($http_authorization !~ "(?i)ApiKey MASTERTOKEN") @{
       return 401;
    @}
    proxy_pass ...; # as above
@}
location ~ /private/ @{
    return 401; # access to instances not explicitly configured is forbidden
@}
@end example

@node Apache<2>,,Nginx<2>,Access control
@anchor{taler-merchant-manual id14}@anchor{3d}
@subsection Apache


For Apache, you should first enable @code{mod_rewrite}:

@example
$ a2enmod rewrite
@end example

Then, you can restrict to an access control token using:

@example
<Location "/">
RewriteEngine On
RewriteCond "%@{HTTP:AUTHORIZATION@}" "!=SECURITYTOKEN"
RewriteRule "(.+)/private/" "-" [F]
RewriteRule "/management/" "-" [F]

ProxyPass "unix:/some/path/here.sock|http://example.com/"
</Location>
@end example

Here, @code{SECURITYTOKEN} should be replaced with the actual shared secret.  Note
that the @code{(.+)} ensures that the above matches all endpoints that include the
string @code{/private/}.  If you only run a single instance, you could simply
specify @code{/private/} without the @code{(.+)} to only configure the access policy for
the default instance.

If you are running different instances on the same backend, you
likely will want to specify different access control tokens for
each instance:

@example
<Location "/instances/foo/">
RewriteEngine On
RewriteCond "%@{HTTP:AUTHORIZATION@}" "!=FOOTOKEN"
RewriteRule "/instances/foo/private/" "-" [F]

ProxyPass ... # as above
</Location>

<Location "/instances/bar/">
RewriteEngine On
RewriteCond "%@{HTTP:AUTHORIZATION@}" "!=BARTOKEN"
RewriteRule "/instances/bar/private/" "-" [F]

ProxyPass ... # as above
</Location>

<Location "/">
RewriteEngine On
RewriteCond "%@{HTTP:AUTHORIZATION@}" "!=MASTERTOKEN"
RewriteRule "/private/" "-" [F]
RewriteRule "/management/" "-" [F]
RewriteRule "(.+)/private/" "-" [F] # reject all others

ProxyPass ... # as above
</Location>
@end example

Please note that these are simply examples of how one could use Nginx or
Apache2 for access control. Both HTTP servers support many other forms of
authentication, including TLS client certificates, HTTP basic and digest
authentication and others, which can all be used (possibly in combination) to
restrict access to the internal API to authorized clients.

System administrators are strongly advised to test their access control
setup before going into production!

@node Status code remapping,,Access control,Secure setup
@anchor{taler-merchant-manual status-code-remapping}@anchor{3e}
@section Status code remapping


Normal API usage leaks instance existence information.
Distinguishing between 404 (Not found) and 403 (Forbidden)
is useful for diagnostics.

For higher security (by leaking less information),
you can add the following fragment,
which remaps all 404 response codes to 403.

@menu
* Nginx: Nginx<3>. 
* Apache: Apache<3>. 

@end menu

@node Nginx<3>,Apache<3>,,Status code remapping
@anchor{taler-merchant-manual id15}@anchor{3f}
@subsection Nginx


@example
error_page 404 =403 /empty.gif;
@end example

@node Apache<3>,,Nginx<3>,Status code remapping
@anchor{taler-merchant-manual id16}@anchor{40}
@subsection Apache


@example
cond %@{STATUS@} =404
set-status 403
@end example

@node Customization,Upgrade procedure,Secure setup,Top
@anchor{taler-merchant-manual customization}@anchor{41}
@chapter Customization


@menu
* Templates:: 
* Static files:: 
* Internationalization:: 
* Limitations:: 

@end menu

@node Templates,Static files,,Customization
@anchor{taler-merchant-manual templates}@anchor{42}
@section Templates


The installation process will install various HTML templates to be served
to trigger the wallet interaction. You may change those templates to your
own design. The templating language used is Mustach, and the templates
are in the @code{share/taler/merchant/templates/} directory.

@node Static files,Internationalization,Templates,Customization
@anchor{taler-merchant-manual static-files}@anchor{43}
@section Static files


The merchant backend also has the ability to serve small static files
under the @code{/static/@{FILENAME@}} endpoint.  This is used by the templating
logic to load a CSS file, but you can also put other resources such as
images or JavaScript.

@node Internationalization,Limitations,Static files,Customization
@anchor{taler-merchant-manual internationalization}@anchor{44}
@section Internationalization


Both templates and static files can be internationalized.  This is done
by having the language of the resource be a part of the filename.
For templates the format is @code{@{BASENAME@}.@{LANGUAGE@}.must}.  The
language is mandatory for templates, the default language is English (en).

For static files, the format is @code{@{BASENAME@}.@{LANGUAGE@}.@{EXT@}} for
internationalized files, and @code{@{BASENAME@}.@{EXT@}} for resources that do not
support internationalization.  The HTTP client will always request
@code{/static/@{BASENAME@}.@{EXT@}}. If @code{@{BASENAME@}.@{EXT@}} exists, that resource is
returned. Otherwise, an internationalized file based on the language
preferences indicated by the browser is returned.

@node Limitations,,Internationalization,Customization
@anchor{taler-merchant-manual limitations}@anchor{45}
@section Limitations


All of the static files must fit into memory and it must be possible for the
process to hold open file handles for all of these files.  You may want
to increase the @code{ulimit} of the @code{taler-merchant-httpd} process if you have
templates for many languages.

The backend determines the MIME type based on the file's extension. The list
of supported extensions is hard-coded and includes common text and image
formats.

The current backend only provides a limited set of variables for the Mustach
template expansion, and does not make use of scopes and other Mustach
features.

@node Upgrade procedure,Tipping visitors,Customization,Top
@anchor{taler-merchant-manual upgrade-procedure}@anchor{46}
@chapter 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
@code{taler-merchant-httpd} process, backup your merchant database (see
PostgreSQL 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 @code{$USER} again.  Then, run:

@example
$ taler-merchant-dbinit
@end example

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:

@example
$ taler-merchant-httpd
@end example

@node Tipping visitors,Advanced topics,Upgrade procedure,Top
@anchor{taler-merchant-manual id17}@anchor{47}@anchor{taler-merchant-manual tipping-visitors}@anchor{48}
@chapter Tipping visitors


@geindex 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.

@menu
* Fund the reserve:: 
* Authorize a tip:: 
* Picking up of the tip:: 

@end menu

@node Fund the reserve,Authorize a tip,,Tipping visitors
@anchor{taler-merchant-manual fund-the-reserve}@anchor{49}@anchor{taler-merchant-manual id18}@anchor{4a}
@section Fund the reserve


@geindex 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 @code{default} using the demo exchange, use:

@example
$ taler-merchant-setup-reserve \
    -a KUDOS:10 \
    -e https://exchange.demo.taler.net/ \
    -m http://localhost:8888/instances/default
@end example

The above command assumes that the merchant runs on localhost on
port 8888.
For more information, including how to transmit authentication information
to the backend, see manpages/taler-merchant-setup-reserve.1.

The command will output a @code{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:

@example
QPE24X8PBX3BZ6E7GQ5VAVHV32FWTTCADR0TRQ183MSSJD2CHNEG
@end example

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
“@indicateurl{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.

@node Authorize a tip,Picking up of the tip,Fund the reserve,Tipping visitors
@anchor{taler-merchant-manual authorize-a-tip}@anchor{4b}@anchor{taler-merchant-manual id19}@anchor{4c}
@section 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
a POST to @code{/private/reserves/$RESERVE_PUB/authorize-tip}. To authorize a
tip, the frontend has to provide the following information in the body of the
POST request:


@itemize -

@item 
The amount of the tip

@item 
The justification (only used internally for the back-office)

@item 
The URL where the wallet should navigate next after the tip was
processed

@item 
The tip-pickup URL (see next section)
@end itemize

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 @code{X-Taler-Tip}
header.

The frontend should handle errors returned by the backend, such as
misconfigured instances or a lack of remaining funds for tipping.

@node Picking up of the tip,,Authorize a tip,Tipping visitors
@anchor{taler-merchant-manual id20}@anchor{4d}@anchor{taler-merchant-manual picking-up-of-the-tip}@anchor{4e}
@section Picking up of the tip


The wallet will POST a JSON object to the shop’s
@code{/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.

@node Advanced topics,Advanced experimental features,Tipping visitors,Top
@anchor{taler-merchant-manual advanced-topics}@anchor{4f}
@chapter Advanced topics


@menu
* Database Scheme:: 
* Configuration format: Configuration format<2>. 

@end menu

@node Database Scheme,Configuration format<2>,,Advanced topics
@anchor{taler-merchant-manual database-scheme}@anchor{50}@anchor{taler-merchant-manual merchantdatabasescheme}@anchor{51}
@section Database Scheme


The merchant database must be initialized using @code{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,
@code{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{taler-merchant-figures/merchant-db,,,,png}

@node Configuration format<2>,,Database Scheme,Advanced topics
@anchor{taler-merchant-manual id21}@anchor{52}
@section Configuration format


@geindex 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
@code{$@{prefix@}/share/taler/config.d/}, in @code{.conf} files. In order to override
these defaults, the user can write a custom .conf file and either pass
it to the component at execution time, or name it @code{taler.conf} and place
it under @code{$HOME/.config/}.

A config file is a text file containing sections, and each section
contains its values. The right format follows:

@example
[section1]
value1 = string
value2 = 23

[section2]
value21 = string
value22 = /path22
@end example

Throughout any configuration file, it is possible to use @code{$}-prefixed
variables, like @code{$VAR}, especially when they represent filesystem
paths. It is also possible to provide defaults values for those
variables that are unset, by using the following syntax:
@code{$@{VAR:-default@}}. However, there are two ways a user can set
@code{$}-prefixable variables:

by defining them under a @code{[paths]} section, see example below,

@example
[paths]
TALER_DEPLOYMENT_SHARED = $@{HOME@}/shared-data
...
[section-x]
path-x = $@{TALER_DEPLOYMENT_SHARED@}/x
@end example

or by setting them in the environment:

@example
$ export VAR=/x
@end example

The configuration loader will give precedence to variables set under
@code{[path]}, though.

The utility @code{taler-config}, which gets installed along with the
exchange, serves to get and set configuration values without directly
editing the @code{.conf}. The option @code{-f} is particularly useful to resolve
pathnames, when they use several levels of @code{$}-expanded variables. See
@code{taler-config --help}.

Note that, in this stage of development, the file
@code{$HOME/.config/taler.conf} can contain sections for @emph{all} the
components. For example, both an exchange and a bank can read values from
it.

The deployment repository@footnote{https://git.taler.net/deployment} contains examples of
configuration file used in our demos. See under @code{deployment/config}.

@quotation

@strong{Note}

Expectably, some components will not work just by using default
values, as their work is often interdependent. For example, a
merchant needs to know an exchange URL, or a database name.
@end quotation

@menu
* Using taler-config: Using taler-config<2>. 

@end menu

@node Using taler-config<2>,,,Configuration format<2>
@anchor{taler-merchant-manual id22}@anchor{53}@anchor{taler-merchant-manual using-taler-002dconfig}@anchor{54}
@subsection Using taler-config


@geindex taler-config

The tool @code{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.

Run:

@example
$ taler-config -s $SECTION
@end example

to list all of the configuration values in section @code{$SECTION}.

Run:

@example
$ taler-config -s $section -o $option
@end example

to extract the respective configuration value for option @code{$option} in
section @code{$section}.

Finally, to change a setting, run:

@example
$ taler-config -s $section -o $option -V $value
@end example

to set the respective configuration value to @code{$value}. Note that you
have to manually restart the Taler backend after you change the
configuration to make the new configuration go into effect.

Some default options will use @code{$}-variables, such as @code{$DATADIR} within
their value. To expand the @code{$DATADIR} or other @code{$}-variables in the
configuration, pass the @code{-f} option to @code{taler-config}. For example,
compare:

@example
$ taler-config -s PATHS \
               -o TALER_DATA_HOME
$ taler-config -f -s PATHS \
               -o TALER_DATA_HOME
@end example

While the configuration file is typically located at
@code{$HOME/.config/taler.conf}, an alternative location can be specified
to @code{taler-merchant-httpd} and @code{taler-config} using the @code{-c}
option.

@node Advanced experimental features,Temporarily Abandoned Features,Advanced topics,Top
@anchor{taler-merchant-manual advanced-experimental-features}@anchor{55}
@chapter Advanced experimental features


This section describes features that most merchants will not
need, or will not need initially.

@menu
* Benchmarking:: 
* Benchmark setup:: 
* Running the benchmark command:: 

@end menu

@node Benchmarking,Benchmark setup,,Advanced experimental features
@anchor{taler-merchant-manual benchmarking}@anchor{56}@anchor{taler-merchant-manual merchantbenchmarking}@anchor{57}
@section Benchmarking


The merchant codebase offers the @code{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 provides them all
the input to accomplish payments. Note that each component will use its
own configuration (as they would do in production).

The main goal of the benchmarking tool is to serve as a starting point (!) for
merchants that are interested in developing stress tests to see how far their
infrastructure can scale.

The current tool has already a few options, but we expect that to deliver
@emph{relevant} results it will need to be customized to better reflect the
workload of a particular merchant.  This customization would at this point
likely involve writing (C) code.  We welcome contributions to make it easier
to customize the benchmark and/or to cover more realistic workloads from the
start.

@node Benchmark setup,Running the benchmark command,Benchmarking,Advanced experimental features
@anchor{taler-merchant-manual benchmark-setup}@anchor{58}
@section Benchmark setup


The @code{taler-merchant-benchmark} tool will automatically launch and configure the
exchange, (Python) bank and other tools required for the benchmark. However,
the configuration file must be provided and have consistent options set.  The
options that require special care include the exchange's public key (which
must match the private key in the file specified by the configuration), the
currency (which must be consistent across the file), the denomination
structure (which must enable payments in the range of 100ths of the unit
currency (often called cents)). Furthermore, the benchmark will set the
Exchange bank account password to be "x", so the configuration must also
specify "x" for the passphrase.  Finally, the bank must be configured to allow
for substantial debt least the transactions by the benchmark run out of
digital cash.

A relatively minimal configuration could look like this:

@example
[PATHS]
# Persistent data storage for the benchmark
TALER_TEST_HOME = benchmark_home/

[taler]
# If you change the currency here, you MUST change it
# throughout the file.
CURRENCY = EUR
CURRENCY_ROUND_UNIT = EUR:0.01

[merchant]
SERVE = tcp
PORT = 8080
DB = postgres

[merchantdb-postgres]
CONFIG = postgres:///talercheck

[exchange]
DB = postgres
SERVE = tcp
PORT = 8081
BASE_URL = http://localhost:8081/
MASTER_PUBLIC_KEY = T1VVFQZZARQ1CMF4BN58EE7SKTW5AV2BS18S87ZEGYS4S29J6DNG

[exchangedb-postgres]
CONFIG = postgres:///talercheck

[auditor]
DB = postgres
SERVE = tcp
PORT = 8083
BASE_URL = http://the.auditor/

[auditordb-postgres]
CONFIG = postgres:///talercheck

[bank]
DATABASE = postgres:///talerbank
SERVE = http
HTTP_PORT = 8082
MAX_DEBT = EUR:5000.0
MAX_DEBT_BANK = EUR:0.0

[merchant-exchange-test]
MASTER_KEY = T1VVFQZZARQ1CMF4BN58EE7SKTW5AV2BS18S87ZEGYS4S29J6DNG
EXCHANGE_BASE_URL = http://localhost:8081/
CURRENCY = EUR

[exchange-account-exchange]
# The account name MUST be 'Exchange'
PAYTO_URI = payto://x-taler-bank/localhost/Exchange
WIRE_RESPONSE = $@{TALER_CONFIG_HOME@}/exchange/account.json
WIRE_GATEWAY_URL = http://localhost:8082/taler-wire-gateway/Exchange/
WIRE_GATEWAY_AUTH_METHOD = basic
USERNAME = Exchange
# The password MUST be 'x'
PASSWORD = x
ENABLE_DEBIT = YES
ENABLE_CREDIT = YES

[fees-x-taler-bank]
WIRE-FEE-2020 = EUR:0.01
WIRE-FEE-2021 = EUR:0.01
WIRE-FEE-2022 = EUR:0.01
WIRE-FEE-2023 = EUR:0.01
WIRE-FEE-2024 = EUR:0.01
WIRE-FEE-2025 = EUR:0.01
WIRE-FEE-2026 = EUR:0.01
WIRE-FEE-2027 = EUR:0.01
CLOSING-FEE-2020 = EUR:0.01
CLOSING-FEE-2021 = EUR:0.01
CLOSING-FEE-2022 = EUR:0.01
CLOSING-FEE-2023 = EUR:0.01
CLOSING-FEE-2024 = EUR:0.01
CLOSING-FEE-2025 = EUR:0.01
CLOSING-FEE-2026 = EUR:0.01
CLOSING-FEE-2027 = EUR:0.01

[coin_eur_ct_1]
value = EUR:0.01
duration_withdraw = 7 days
duration_spend = 2 years
duration_legal = 3 years
fee_withdraw = EUR:0.00
fee_deposit = EUR:0.00
fee_refresh = EUR:0.01
fee_refund = EUR:0.01
rsa_keysize = 1024

[coin_eur_ct_10]
value = EUR:0.10
duration_withdraw = 7 days
duration_spend = 2 years
duration_legal = 3 years
fee_withdraw = EUR:0.01
fee_deposit = EUR:0.01
fee_refresh = EUR:0.03
fee_refund = EUR:0.01
rsa_keysize = 1024

[coin_eur_1]
value = EUR:1
duration_withdraw = 7 days
duration_spend = 2 years
duration_legal = 3 years
fee_withdraw = EUR:0.01
fee_deposit = EUR:0.01
fee_refresh = EUR:0.03
fee_refund = EUR:0.01
rsa_keysize = 1024

[coin_eur_5]
value = EUR:5
duration_withdraw = 7 days
duration_spend = 2 years
duration_legal = 3 years
fee_withdraw = EUR:0.01
fee_deposit = EUR:0.01
fee_refresh = EUR:0.03
fee_refund = EUR:0.01
rsa_keysize = 1024

@end example

Note that the public key must match the exchange's
private key and that the PostgreSQL database must
exist before launching the benchmark.  You also
will need to ensure that the Exchange's
details are set up.
For details, see the Exchange Operator Manual.

@node Running the benchmark command,,Benchmark setup,Advanced experimental features
@anchor{taler-merchant-manual running-the-benchmark-command}@anchor{59}
@section Running the benchmark command


The tool takes all of the values it needs from the command line, with
one of them being mandatory:


@itemize -

@item 
@code{--exchange-account=SECTION} Specifies which configuration
section specifies the bank account for the exchange that
should be used for the benchmark. For the example
configuration above, the SECTION value provided must be
@code{exchange-account-exchange}.
@end itemize

The tool comes with two operation modes: @emph{ordinary}, and @emph{corner}.
The first just executes normal payments, meaning that it uses the
default instance and make sure that all payments get aggregated. The
second gives the chance to leave some payments unaggregated, and also to
use merchant instances other than the default (which is, actually, the
one used by default by the tool).

Note: the ability of driving the aggregation policy is useful for testing
the back-office facility.

Any subcommand is also equipped with the canonical @code{--help} option, so
feel free to issue the following command in order to explore all the
possibilities. For example:

@example
$ taler-merchant-benchmark corner --help
@end example

will show all the options offered by the @emph{corner} mode. Among the most
interesting, there are:


@itemize -

@item 
@code{--two-coins=TC} This option instructs the tool to perform @emph{TC}
many payments that use two coins, because normally only one coin is
spent per payment.

@item 
@code{--unaggregated-number=UN} This option instructs the tool to
perform @emph{UN} (one coin) payments that will be left unaggregated.
@end itemize

As for the @code{ordinary} subcommand, it is worth explaining the following
options:


@itemize -

@item 
@code{--payments-number=PN} Instructs the tool to perform @emph{PN} payments.

@item 
@code{--tracks-number=TN} Instructs the tool to perform @emph{TN} tracking
operations. Note that the @strong{total} amount of operations will be two
times @emph{TN}, since "one" tracking operation accounts for
@code{/track/transaction} and @code{/track/transfer}. This command should
only be used to see if the operation ends without problems, as no
actual measurement of performance is provided (despite of the
’benchmark’ word used in the tool’s name).
@end itemize

@node Temporarily Abandoned Features,Index,Advanced experimental features,Top
@anchor{taler-merchant-manual temporarily-abandoned-features}@anchor{5a}
@chapter Temporarily Abandoned Features


@menu
* Installing Taler using Docker:: 

@end menu

@node Installing Taler using Docker,,,Temporarily Abandoned Features
@anchor{taler-merchant-manual installing-taler-using-docker}@anchor{5b}
@section 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 @code{docker} command should connect to a @code{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  @footnote{@w{(1)} 
@indicateurl{https://docs.docker.com/}
} 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 @code{git://git.taler.net/deployment}
codebase:

@example
$ git clone git://git.taler.net/deployment
@end example

Now we actually build the merchant’s image. From the same directory as
above:

@example
$ cd deployment/docker/merchant/
$ docker-compose build
@end example

If everything worked as expected, the merchant is ready to be launched.
From the same directory as the previous step:

@example
# Recall: the docker-machine should be up and running.
$ docker-compose up
@end example

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, for example:

@example
$ wget -O - http://$(docker-machine ip)/
# A greeting message should be returned by the merchant.
@end example

@node Index,,Temporarily Abandoned Features,Top
@unnumbered Index


@printindex ge


@c %**end of body
@bye