summaryrefslogtreecommitdiff
path: root/taler-merchant-manual.rst
blob: 647d242d8eb7833c608e4329c90d17fc80b0d997 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
.. _ffoobar:

GNU Taler Merchant Backend Operator Manual
##########################################

Introduction
============

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.

.. _About-this-manual:

About this manual
-----------------

This manual targets system administrators who want to install a GNU
Taler merchant *backend*.

We expect some moderate familiarity with the compilation and
installation of Free Software packages. An understanding of cryptography
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.

.. _Architecture-overview:

Architecture overview
---------------------

.. 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
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:

-  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.
   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
   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 implementation only supports
   Postgres, but the code could be easily extended to support another
   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:

.. image:: arch-api.png

.. index:: 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.

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.


Terminology
===========

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

Instances
---------

.. 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).

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
--------------------

.. 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.
Sharing order URLs is explicitly allowed: if a user shares and 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 *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.

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 after the
customer paid and before 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.


Installation
============

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

.. _Generic-instructions:

Generic instructions
--------------------

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.

.. _Installation-of-dependencies:

Installation of dependencies
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

-  libsqlite3 >= 3.16.2

-  libunistring >= 0.9.3

-  libcurl >= 7.26 (or libgnurl >= 7.26)

-  libqrencode >= 4.0.0

-  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.6, including libpq

-  GNU libmicrohttpd >= 0.9.71

-  GNUnet >= 0.14.0 (from `source tarball <http://ftpmirror.gnu.org/gnunet/>`__)

-  GNU Taler exchange (see `release announcement <https://mail.gnu.org/archive/cgi-bin/namazu.cgi?query=taler&idxname=info-gnu&max=20&result=normal&sort=date:late>`__)

Except for the last two, these are available in most GNU/Linux distributions
and should just be installed using the respective package manager. Be careful
with GNU libmicrohttpd; here, some distributions only include an older version
that will not work.

While you are in the GNU Taler exchange
`download directory <http://ftpmirror.gnu.org/taler/>`__,
you might as well also download the tarball for GNU Taler merchant.

GNU Taler components version numbers follow the ``MAJOR.MINOR.MICRO`` format.
The general rule for compatibility is that ``MAJOR`` and ``MINOR`` must match.
Exceptions to this general rule are documented in the release notes.
For example, Taler merchant 0.8.0 is compatible with Taler exchange 0.8.1.

The following sections will provide detailed instructions for installing
the ``libgnunetutil`` and GNU Taler exchange dependencies.

.. _Installing-libgnunetutil:

Installing GNUnet
^^^^^^^^^^^^^^^^^

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

.. code-block:: console

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

If you did not specify a prefix, GNUnet will install to ``/usr/local``,
which requires you to run the last step as ``root``.
The ``ldconfig`` command (also run as ``root``) makes the
shared object libraries (``.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!


.. _Installing-the-GNU-Taler-exchange:

Installing the GNU Taler exchange
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. index:: exchange

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

.. code-block:: console

   $ ./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!


.. _Installing-the-GNU-Taler-merchant-backend:

Installing the GNU Taler merchant backend
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. index:: backend

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:

.. code-block:: console

     $ ./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``.

You have to specify ``--with-exchange=/usr/local`` and/or
``--with-gnunet=/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
------------------------------------

.. index:: Wheezy
.. index:: Jessie
.. index:: Stretch
.. index:: Debian

Debian wheezy is too old and lacks most of the packages required.
Debian jessie is better, but still lacks PostgreSQL 9.6.

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

.. code-block:: console

   # apt-get install \
     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://ftp.gnu.org/gnu/libmicrohttpd/libmicrohttpd-latest.tar.gz
   # wget https://ftp.gnu.org/gnu/libmicrohttpd/libmicrohttpd-latest.tar.gz.sig
   # gpg -v libmicrohttpd-latest.tar.gz # Should show signed by 939E6BE1E29FC3CC
   # tar xf libmicrohttpd-latest.tar.gz
   # cd libmicrohttpd-0*
   # ./configure
   # make install

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

.. code-block:: console

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

Note that stretch requires ``libargon2-0-dev``,
while later versions of Debian require ``libargon2-dev``.

For the rest of the installation, follow the generic installation
instructions starting with the installation of libgnunetutil. Note that
if you used the Debian stretch instructions above, you need to pass
``--with-microhttpd=/usr/local/`` to all ``configure`` invocations.


How to configure the merchant’s backend
=======================================

.. 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
default, the file ``$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 ``taler-config``
commands given as examples. For more information on ``taler-config``,
see `Using taler-config <#Using-taler_002dconfig>`__.

.. _Backend-options:

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:

.. code-block:: ini

      [MERCHANT]/SERVE = TCP | UNIX

If given,

   -  ``TCP``, then we need to set the TCP port in ``[MERCHANT]/PORT``

   -  ``UNIX``, then we need to set the unix domain socket path and mode
      in ``[MERCHANT]/UNIXPATH`` and ``[MERCHANT]/UNIXPATH_MODE``. The
      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.

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

.. code-block:: console

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



Currency
^^^^^^^^

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

.. code-block:: ini

      [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/:

.. code-block:: console

   $ taler-config -s TALER -o CURRENCY -V KUDOS


Database
^^^^^^^^

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

.. code-block:: ini

      [MERCHANT]/DB

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.

For postgres, you need to provide:

.. code-block:: ini

      [MERCHANTDB-postgres]/CONFIG

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

.. code-block:: console

   $ sudo -u postgres createuser -d $USER

as the Postgres database administrator (usually ``postgres``) to
grant ``$USER`` the ability to create new databases. Next, you should
as ``$USER`` run:

.. code-block:: console

   $ createdb $DBNAME

to create the backend’s database. Here, ``$DBNAME`` must match the
database name given in the configuration file.

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

.. code-block:: console

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

Now you should create the tables and indices. To do this, run as ``$USER``:

.. code-block:: console

   $ 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
^^^^^^^^

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:

      .. code-block:: console

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

   -  The “MASTER_KEY” option specifies the exchange’s master public key
      in base32 encoding. For the Taler demonstrator, use:

      .. code-block:: console

         $ taler-config -s MERCHANT-EXCHANGE-demo \
             -o MASTER_KEY \
             -V CQQZ9DY3MZ1ARMN5K1VKDETS04Y2QCKMMCFHZSWJWWVN82BTTH00

   -  The “CURRENCY” option specifies the exchange’s currency.
      For the Taler demonstrator, use:

      .. code-block:: console

         $ taler-config -s MERCHANT-EXCHANGE-demo \
             -o CURRENCY \
             -V KUDOS

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.



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

   -  The “AUDITOR_BASE_URL” option specifies the auditor’s base URL. For example,
      to use the Taler demonstrator's auditor, specify:

      .. code-block:: console

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

   -  The “AUDITOR_KEY” option specifies the auditor's public key
      in base32 encoding. For the Taler demonstrator, use:

      .. code-block:: console

         $ taler-config -s MERCHANT-AUDITOR-demo \
             -o AUDITOR_KEY \
             -V FIXMEBADVALUENEEDTOGETTHERIGHTVALUEHEREEVENTUALLY000

   -  The “CURRENCY” option specifies the auditor’s currency.
      For the Taler demonstrator, use:

      .. code-block:: console

         $ taler-config -s MERCHANT-AUDITOR-demo \
             -o CURRENCY \
             -V KUDOS


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.


.. _Sample-backend-configuration:

Sample backend configuration
----------------------------

.. index:: configuration

The following is an example for a complete backend configuration:

.. code-block:: ini

   [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

Given the above configuration, the backend will use a database named
``donations`` within Postgres.

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

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

.. _Launching-the-backend:

Launching the backend
---------------------

.. index:: backend
.. index:: taler-merchant-httpd

Assuming you have configured everything correctly, you can launch the
merchant backend as ``$USER`` using

.. code-block:: console

   $ taler-merchant-httpd

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

.. code-block:: console

   $ curl http://localhost:8888/

should return the message

.. code-block:: none

   Hello, I'm a merchant's Taler backend. This HTTP server is not for humans.

Please note that your backend is right now likely globally reachable.
Production systems should be configured to bind to a UNIX domain socket
and use TLS for improved network privacy, see :ref:`Secure setup <Secure-setup>`.


.. index:: instance
.. _Instance-setup:

Instance setup
==============

Before using the backend, you must at least configure the "default" instance.


KUDOS Accounts
--------------

The main configuration data that must be provided for each instance
is the bank account information.

In order to receive payments, the merchant backend needs to
communicate bank account details to the exchange.

The bank account information is provided in the form of a ``payto://``-URI.
See RFC 8905 for the format of ``payto://``-URIs.

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


IBAN Accounts
-------------

When deploying Taler with the real banking system, you primarily need to
change the currency of the configuration from KUDOS to the actual currency
(such as EUR, USD, CHF) and provide a payto://-URI of your real bank
account. In Europe, this will involve knowing your IBAN number. If you have an
IBAN, the corresponding payto://-URI is simply "payto://iban/$IBAN" where
"$IBAN" must be replaced with the actual IBAN number.


Setup
------

With the knowledge of the payto://-URI, instances can be configured by POSTing
a request to :http:post:`/private/instances`.  To create a first instance,
create a file ``instance.json`` with an `InstanceConfigurationMessage`

.. code-block:: json

   {
     payto_uris : [ "$PAYTO_URI" ],
     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 },
   }

In the text above, you must replace "$PAYTO_URI" with your actual
payto://-URI. Also, be sure to replace KUDOS with the fiat currency if the
setup is for an actual bank. The "name" field will be shown as the name of
your shop. The "address" field is expected to contain your shop's physical
address. The various defaults specify defaults for transaction fees your shop
is willing to cover, how long offers made to the customer are valid, and how
long the exchange has before it must wire the funds to your bank
account. Those defaults can be modified for individual orders.
For details, see the :ref:`contract terms <contract-terms>` specification.

You can then create the instance using:

.. code-block:: console

   $ wget --post-file=instance.json http://localhost:8888/private/instances

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".

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>`.


.. _Secure-setup:

Secure setup
============

.. index:: security
.. index:: TLS

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.

Using UNIX domain sockets
-------------------------

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

.. code-block:: console

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

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 *may* use a
host-based firewall to block access to the TCP port of the merchant backend,
but this is *not recommended*.  Relying on NAT or network firewalls for access
control is gross negligence.


Reverse proxy configuration
---------------------------

Nginx
^^^^^

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

.. code-block:: nginx

      proxy_pass http://unix:/some/path/here.sock;
      proxy_redirect off;
      proxy_set_header Host $host;
      proxy_set_header X-Forwarded-Host "example.com";
      proxy_set_header X-Forwarded-Proto "https";

Note that the above assumes your domain name is ``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 ``taler-merchant-httpd``
process after changing the ``SERVE`` configuration.

Apache
^^^^^^

In Apache, make sure you have "mod_proxy", "mod_proxy_http" and
"mod_headers" enabled:

.. code-block:: console

   $ a2enmod proxy
   $ a2enmod proxy_http
   $ a2enmod headers

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

.. code-block:: apacheconf

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

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

The above configuration(s) are both incomplete. You must still additionally
setup access control!


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.

Nginx
^^^^^

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

.. code-block:: nginx

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

Here, "SECURITYTOKEN" should be replaced with the actual shared secret.  Note
that the "~" ensures that the above matches all endpoints that include the
string "/private/".  If you only run a single instance, you could simply
specify "/private/" without the "~" 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:

.. code-block:: nginx

      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 ~ /private/ {
          return 401; // access to instances not explicitly configured is forbidden
      }

Apache
^^^^^^

For Apache, you should first enable "mod_rewrite":

.. code-block:: console

   $ a2enmod rewrite

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

.. code-block:: apacheconf

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

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

Here, "SECURITYTOKEN" should be replaced with the actual shared secret.  Note
that the "(.+)" ensures that the above matches all endpoints that include the
string "/private/".  If you only run a single instance, you could simply
specify "/private/" without the "~" 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:

.. code-block:: apacheconf

       <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 "(.+)/private/" "-" [F] # reject all others

       ProxyPass ... # as above
       </Location>

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 admininistrators are strongly advised to test their access control
setup before going into production!


Customization
=============

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 ``share/taler/merchant/templates/`` directory.


Static files
------------

The merchant backend also has the ability to serve small static files
under the ``/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.

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 ``{BASENAME}.{LANGUAGE}.must``.  The
language is mandatory for templates, the default language is English (en).

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

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 "ulimit" of the ``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.



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:

.. code-block:: console

   $ taler-merchant-dbinit

to upgrade the database to the latest schema.  After that, you may again
REVOKE the database permissions. Finally, restart the HTTP service, either via
your systemd or init system, or directly using:

.. code-block:: console

   $ taler-merchant-httpd


.. _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:

.. code-block:: console

   $ 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:

.. code-block:: none

   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
misconfigured 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
--------------------

.. 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
``${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:

.. code-block:: ini

   [section1]
   value1 = string
   value2 = 23

   [section2]
   value21 = string
   value22 = /path22

Throughout any configuration file, it is possible to use ``$``-prefixed
variables, like ``$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:
``${VAR:-default}``. However, there are two ways a user can set
``$``-prefixable variables:

by defining them under a ``[paths]`` section, see example below,

.. code-block:: ini

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

or by setting them in the environment:

.. code-block:: console

   $ export VAR=/x

The configuration loader will give precedence to variables set under
``[path]``, though.

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

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

The `deployment repository <https://git.taler.net/deployment>`_ contains examples of
configuration file used in our demos. See under ``deployment/config``.

   **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.

.. _Using-taler_002dconfig:

Using taler-config
^^^^^^^^^^^^^^^^^^

.. index:: 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.

Run

.. code-block:: console

   $ taler-config -s $SECTION

to list all of the configuration values in section ``$SECTION``.

Run

.. code-block:: console

   $ taler-config -s $section -o $option

to extract the respective configuration value for option ``$option`` in
section ``$section``.

Finally, to change a setting, run

.. code-block:: console

   $ taler-config -s $section -o $option -V $value

to set the respective configuration value to ``$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 ``$DATADIR`` within
their value. To expand the ``$DATADIR`` or other ``$``-variables in the
configuration, pass the ``-f`` option to ``taler-config``. For example,
compare:

.. code-block:: console

   $ taler-config -s PATHS \
                  -o TALER_DATA_HOME
   $ 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.



Advanced experimental features
==============================

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

.. _MerchantBenchmarking:

Benchmarking
------------

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
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
*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.


Benchmark setup
---------------

The ``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:

.. literalinclude:: merchant-benchmark.conf


Note that the public key must match the exchange's
private key and that the Postgres database must
exist before launching the benchmark.  You also
will need to ensure that the Exchange's
details are setup, usually by running

.. code-block:: console

   $ taler-exchange-wire -c $CONFIG_FILE
   $ taler-exchange-keyup -c $CONFIG_FILE

where "$CONFIG_FILE" should be replaced by
the configuration file that is to be used.


Running the benchmark command
-----------------------------

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

-  ``--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
   "exchange-account-exchange".

The tool comes with two operation modes: *ordinary*, and *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 backoffice facility.

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

.. code-block:: console

   $ taler-merchant-benchmark corner --help

will show all the options offered by the *corner* mode. Among the most
interesting, there are:

-  ``--two-coins=TC`` This option instructs the tool to perform *TC*
   many payments that use two coins, because normally only one coin is
   spent per payment.

-  ``--unaggregated-number=UN`` This option instructs the tool to
   perform *UN* (one coin) payments that will be left unaggregated.

As for the ``ordinary`` subcommand, it is worth explaining the following
options:

-  ``--payments-number=PN`` Instructs the tool to perform *PN* payments.

-  ``--tracks-number=TN`` Instructs the tool to perform *TN* tracking
   operations. Note that the **total** amount of operations will be two
   times *TN*, since "one" tracking operation accounts for
   ``/track/transaction`` and ``/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).




Temporarily Abandoned Features
==============================

.. [1]
   https://docs.docker.com/


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:

.. code-block:: console

   $ git clone git://git.taler.net/deployment

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

.. code-block:: console

   $ cd deployment/docker/merchant/
   $ docker-compose build

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

.. code-block:: console

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

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:

.. code-block:: console

   $ curl http://$(docker-machine ip)/
   # A greeting message should be returned by the merchant.