document taler-merchant-benchmark better

2 files changed, 185 insertions, 58 deletions

diff --git a/merchant-benchmark.conf b/merchant-benchmark.conf
new file mode 100644
index 00000000..3702302d
--- /dev/null
+++ b/merchant-benchmark.conf
@@ -0,0 +1,123 @@
+[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
+
diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst
index a62212ad..60fe441f 100644
--- a/taler-merchant-manual.rst
+++ b/taler-merchant-manual.rst
@@ -1031,7 +1031,7 @@ likely will want to specify different access control tokens for
 each instance:
 
     ::
-       
+
       location ~ ^/instances/foo/private/ {
           if ($http_authorization !~ "(?i)ApiKey FOOTOKEN") {
              return 401;
@@ -1056,12 +1056,12 @@ each instance:
 
 Apache
 ^^^^^^
-    
+
 For Apache, you should first enable "mod_rewrite":
 
     ::
        a2enmod rewrite
-       
+
 Then, you can restrict to an access control token using:
 
     ::
@@ -1091,7 +1091,7 @@ each instance:
 
        ProxyPass ... # as above
        </Location>
-       
+
        <Location "/instances/bar/">
        RewriteEngine On
        RewriteCond "%{HTTP:AUTHORIZATION}" "!=BARTOKEN"
@@ -1099,7 +1099,7 @@ each instance:
 
        ProxyPass ... # as above
        </Location>
-       
+
        <Location "/">
        RewriteEngine On
        RewriteCond "%{HTTP:AUTHORIZATION}" "!=MASTERTOKEN"
@@ -1463,83 +1463,84 @@ option.
 
 
 
-
-Temporarily Abandoned Features
+Advanced experimental features
 ==============================
 
-This documentation is outdated, or rather what it describes
-has not been properly maintained and is not expected to work
-today. However, we do hope to get it working again in the
-future (help appreciated).
-
+This section describes features that most merchants will not
+need, or will not need initially.
 
 .. _MerchantBenchmarking:
 
 Benchmarking
 ------------
 
-.. index:: testing database
-
-NOTE: This section is dated and should be reviewed!
-
-FIXME: which coin denominations are needed for the benchmark?
-
-FIXME: provide "minimum" configuration file!
-
-DOCUMENT how to run taler-merchant-benchmark: configuration MUST set exchange bank password to 'x'!
-
-FIXME: explain Postgres setup!
-
+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).
 
-Setup: create Exchange account and two user accounts ``42`` and ``43`` at
-the bank:
+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.
 
-   $ taler-bank-manage django add_bank_account Exchange
-   $ taler-bank-manage django add_bank_account 42
-   $ taler-bank-manage django add_bank_account 43
 
-Setup exchange password using:
+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.
 
-   $ taler-bank-manage django changepassword_unsafe Exchange PASSWORD
+A relatively minimal configuration could look like this:
 
-Configure merchant and exchange, then run:
+.. literalinclude:: merchant-benchmark.conf
 
-::
 
-   $ taler-exchange-dbinit
-   $ taler-exchange-keyup
-   $ taler-merchant-dbinit
+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
 
-Launch bank, exchange and merchant backends:
+  ::
 
-::
+     taler-exchange-wire -c $CONFIG_FILE
+     taler-exchange-keyup -c $CONFIG_FILE
 
-   $ taler-bank-manage serve-http &
-   $ taler-exchange-httpd &
-   $ taler-merchant-httpd &
+where "$CONFIG_FILE" should be replaced by
+the configuration file that is to be used.
 
 
-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).
+Running the benchmark command
+-----------------------------
 
 The tool takes all of the values it needs from the command line, with
-some of them being mandatory. Among those, we have:
-
--  ``--bank-url=URL`` Assume that the bank is serving under the base URL
-   *URL*. This option is only actually used by the tool to check if the
-   bank was well launched.
+one of them being mandatory:
 
--  ``--merchant-url=URL`` Reach the merchant through *URL*, for
-   downloading contracts and sending payments.
+-  ``--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 then comes with two operation modes: *ordinary*, and *corner*.
+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
@@ -1580,11 +1581,14 @@ options:
    actual measurement of performance is provided (despite of the
    ’benchmark’ work used in the tool’s name).
 
-.. [1]
-   https://docs.docker.com/
 
 
 
+Temporarily Abandoned Features
+==============================
+
+.. [1]
+   https://docs.docker.com/
 
 
 Installing Taler using Docker