-improve merchant manual

1 files changed, 70 insertions, 7 deletions

diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst
index 2d354160..c49a4189 100644
--- a/taler-merchant-manual.rst
+++ b/taler-merchant-manual.rst
@@ -505,6 +505,14 @@ To run the Taler backend on TCP port 8888, use:
    $ taler-config -s MERCHANT -o SERVE -V TCP
    $ taler-config -s MERCHANT -o PORT -V 8888
 
+.. note::
+
+   When using the Debian/Ubuntu packages, these options are already
+   configured in the /etc/taler/conf.d/merchant.conf configuration file.
+
+   If you need to change them, you should edit /etc/taler/override.conf,
+   for example by passing "-c /etc/taler/override.conf" to the
+   ``taler-config`` commands above.
 
 
 Currency
@@ -525,6 +533,15 @@ https://exchange.demo.taler.net/:
 
    $ taler-config -s TALER -o CURRENCY -V KUDOS
 
+.. note::
+
+   When using the Debian/Ubuntu packages, these options should be
+   configured in the ``/etc/taler/taler.conf`` configuration file
+   (alternatively, you can also edit /etc/taler/overrides.conf).
+   However, you must edit the ``taler.conf`` file manually and must
+   not use ``taler-config`` to do this, as that would inline the include
+   directives and destroy the carefully setup path structure.
+
 
 Database
 ^^^^^^^^
@@ -542,7 +559,14 @@ specifies which DBMS is to be used. However, currently only the value
 In addition to selecting the DBMS software, the backend requires
 DBMS-specific options to access the database.
 
-For postgres, you need to provide:
+.. note::
+
+   When using the Debian/Ubuntu packages, the database should already
+   be configured in the ``/etc/taler/secrets/merchant-db.secret.conf``
+   configuration file.  The ``talermerchant`` database is also already
+   configured, so you can skip everything in this section.
+
+For the ``postgres`` backend, you need to provide:
 
 .. code-block:: ini
 
@@ -638,6 +662,14 @@ 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.
 
+.. 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.
+
 
 
 Auditor
@@ -646,7 +678,7 @@ 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:
+4that 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:
@@ -682,6 +714,14 @@ auditors must use the same currency: If the currency does not match the main
 currency from the ``TALER`` section, the auditor is ignored.  If you need to
 support multiple currencies, you need to configure a backend per currency.
 
+.. note::
+
+   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.
+
 
 .. _Sample-backend-configuration:
 
@@ -750,6 +790,19 @@ 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.
 
+.. note::
+
+   When using the Debian/Ubuntu packages, the systemd configuration
+   will already exist. You only need to enable and start the service
+   using ``systemctl enable taler-merchant`` and
+   ``systemctl start taler-merchant``. Additionally, you should
+   review the ``taler-merchant.conf`` under
+   ``/etc/{apache2,nginx}/sites-available/``, symlink it to
+   ``sites-enabled/`` and restart your HTTP server. After that, you
+   should be able to visit the merchant backend at the respective
+   HTTP(S) endpoint.
+
+
 If everything worked as expected, the command
 
 .. code-block:: console
@@ -774,11 +827,21 @@ and use TLS for improved network privacy, see :ref:`Secure setup <Secure-setup>`
 Instance setup
 ==============
 
-Before using the backend, you must at least configure the ``default`` instance.
-The ``default`` instance can also create / delete / configure other instances,
-similar to the ``root`` account on UNIX.
-The following documentation shows how to handle any instance, so you should read
-it twice, first creating the ``default`` instance, then creating normal ones.
+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 ``curl`` commands given below.
+
+The first step for using the backend involves the creation of a ``default``
+instance. The ``default`` instance can also create / delete / configure other
+instances, similar to the ``root`` account on UNIX.  When no instance exists
+and ``taler-merchant-httpd`` was started without the ``--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.
 
 .. note::
   A security concern is that normal API usage leaks instance existence.