12 files changed, 404 insertions, 0 deletions
diff --git a/doc/sphinx/frags/README.md b/doc/sphinx/frags/README.md
new file mode 100644
index 0000000..5070c7f
--- /dev/null
+++ b/doc/sphinx/frags/README.md
@@ -0,0 +1,18 @@
+# docs.git/frags
+
+This directory contains fragments to be included by the directive:
+
+  .. include:: RELATIVE-FILE-NAME
+
+If the fragment includes header lines, you MUST include it at top-level
+(no indentation for the directive).
+
+Otherwise, it can be included at either top-level or indented.
+
+See <https://docutils.sourceforge.io/docs/ref/rst/directives.html#including-an-external-document-fragment>.
+
+Tips:
+
+- Don't put index entries in frags/* files.
+  (They will result in a Sphinx warning.)
+  Instead, keep them in the *including* text.
diff --git a/doc/sphinx/frags/configuration-format.rst b/doc/sphinx/frags/configuration-format.rst
new file mode 100644
index 0000000..f9b28e1
--- /dev/null
+++ b/doc/sphinx/frags/configuration-format.rst
@@ -0,0 +1,69 @@
+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:
+
+.. 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
+component. For example, both an exchange and a bank can read values from
+it.
+
+The repository ``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.
diff --git a/doc/sphinx/frags/installing-anastasis-gtk.rst b/doc/sphinx/frags/installing-anastasis-gtk.rst
new file mode 100644
index 0000000..b9d5dc3
--- /dev/null
+++ b/doc/sphinx/frags/installing-anastasis-gtk.rst
@@ -0,0 +1,31 @@
+The following steps assume at least the GNUnet, gnunet-gtk and Anastasis
+dependencies are installed.
+
+First, unpack the anastasis-gtk tarball and change into the resulting
+directory.  Then, use the following commands to build and install
+anastasis-gtk:
+
+.. code-block:: console
+
+     $ ./configure [--prefix=PFX] \
+                   [--with-gnunet=GNUNETPFX] \
+                   [--with-exchange=EXCHANGEPFX] \
+                   [--with-anastasis=ANASTASISPFX]
+     $ # 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, anastasis-gtk will be installed to
+``/usr/local``, which requires you to run the last step as ``root``.
+
+You have to specify ``-with-anastasis=/usr/local``, ``--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 anastasis-gtk would then fail.
diff --git a/doc/sphinx/frags/installing-anastasis.rst b/doc/sphinx/frags/installing-anastasis.rst
new file mode 100644
index 0000000..7978b71
--- /dev/null
+++ b/doc/sphinx/frags/installing-anastasis.rst
@@ -0,0 +1,30 @@
+The following steps assume all dependencies are installed.
+
+First, unpack the Anastasis tarball and change into
+the resulting directory.
+Then, use the following commands to build and install Anastasis:
+
+.. 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, Anastasis will be installed 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 Anastasis backend would
+then fail.
diff --git a/doc/sphinx/frags/installing-debian.rst b/doc/sphinx/frags/installing-debian.rst
new file mode 100644
index 0000000..24f4d20
--- /dev/null
+++ b/doc/sphinx/frags/installing-debian.rst
@@ -0,0 +1,59 @@
+To install the GNU Taler Debian packages, first ensure that you have
+the right Debian distribution. At this time, the packages are built for
+Sid, which means you should use a system which at least includes
+unstable packages in its source list.  We recommend using APT pinning
+to limit unstable packages to those explicitly requested. To do this,
+set your ``/etc/apt/preferences`` as follows:
+
+.. code-block::
+
+   Package: *
+   Pin: release a=stable
+   Pin-Priority: 700
+
+   Package: *
+   Pin: release a=testing
+   Pin-Priority: 650
+
+   Package: *
+   Pin: release a=unstable
+   Pin-Priority: 600
+
+   Package: *
+   Pin: release l=Debian-Security
+   Pin-Priority: 1000
+
+A typical ``/etc/apt/sources.list`` file for this setup
+which combines Debian stable with more recent packages
+from testing and unstable would look like this:
+
+.. code-block::
+
+   deb http://ftp.ch.debian.org/debian/ buster main
+   deb http://security.debian.org/debian-security buster/updates main
+   deb http://ftp.ch.debian.org/debian/ testing main
+   deb http://ftp.ch.debian.org/debian/ unstable main
+
+Naturally, you may want to use different mirrors depending on your region.
+Additionally, you must add a file to import the GNU Taler packages. Typically,
+this is done by adding a file ``/etc/apt/sources.list.d/taler.list`` that
+looks like this:
+
+.. code-block::
+
+   deb https://deb.taler.net/apt/debian sid main
+
+Next, you must import the Taler Systems SA public package signing key
+into your keyring and update the package lists:
+
+.. code-block:: console
+
+   # wget -O - https://taler.net/taler-systems.gpg.key | apt-key add -
+   # apt update
+
+.. note::
+
+   You may want to verify the correctness of the Taler Systems key out-of-band.
+
+Now your system is ready to install the official GNU Taler binary packages
+using apt.
diff --git a/doc/sphinx/frags/installing-gnunet-gtk.rst b/doc/sphinx/frags/installing-gnunet-gtk.rst
new file mode 100644
index 0000000..d4c8319
--- /dev/null
+++ b/doc/sphinx/frags/installing-gnunet-gtk.rst
@@ -0,0 +1,28 @@
+The following steps assume at least the GNUnet and Gtk+ dependencies are installed.
+
+First, unpack the gnunet-gtk tarball and change into the resulting directory.
+Then, use the following commands to build and install gnunet-gtk:
+
+.. code-block:: console
+
+     $ ./configure [--prefix=$PFX] \
+                   [--with-gnunet=$GNUNETPFX]
+     $ # Each dependency can be fetched from non standard locations via
+     $ # the '--with-<LIBNAME>' option. See './configure --help'.
+     $ make
+     # make install
+
+It is highly recommended to use the same prefix ($PFX) for gnunet-gtk that was
+used for GNUnet ($GNUNETPFX).  If you did not specify a prefix, gnunet-gtk
+will be installed 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 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 ``$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 gnunet-gtk would then fail.
diff --git a/doc/sphinx/frags/installing-gnunet.rst b/doc/sphinx/frags/installing-gnunet.rst
new file mode 100644
index 0000000..99ff472
--- /dev/null
+++ b/doc/sphinx/frags/installing-gnunet.rst
@@ -0,0 +1,21 @@
+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:
+
+.. 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.
diff --git a/doc/sphinx/frags/installing-taler-exchange.rst b/doc/sphinx/frags/installing-taler-exchange.rst
new file mode 100644
index 0000000..1b8e96b
--- /dev/null
+++ b/doc/sphinx/frags/installing-taler-exchange.rst
@@ -0,0 +1,16 @@
+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.
diff --git a/doc/sphinx/frags/installing-taler-merchant.rst b/doc/sphinx/frags/installing-taler-merchant.rst
new file mode 100644
index 0000000..249d5d7
--- /dev/null
+++ b/doc/sphinx/frags/installing-taler-merchant.rst
@@ -0,0 +1,34 @@
+GNU Taler merchant has these additional dependencies:
+
+- libqrencode >= 4.0.0
+
+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.
diff --git a/doc/sphinx/frags/installing-ubuntu.rst b/doc/sphinx/frags/installing-ubuntu.rst
new file mode 100644
index 0000000..1283104
--- /dev/null
+++ b/doc/sphinx/frags/installing-ubuntu.rst
@@ -0,0 +1,27 @@
+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 ``/etc/apt/sources.list.d/taler.list`` file for this setup
+would look like this:
+
+.. code-block::
+
+   deb https://deb.taler.net/apt/ubuntu/ focal-fossa main
+
+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:
+
+.. code-block:: console
+
+   # wget -O - https://taler.net/taler-systems.gpg.key | apt-key add -
+   # apt update
+
+.. note::
+
+   You may want to verify the correctness of the Taler Systems key out-of-band.
+
+Now your system is ready to install the official GNU Taler binary packages
+using apt.
diff --git a/doc/sphinx/frags/list-of-dependencies.rst b/doc/sphinx/frags/list-of-dependencies.rst
new file mode 100644
index 0000000..f0a183f
--- /dev/null
+++ b/doc/sphinx/frags/list-of-dependencies.rst
@@ -0,0 +1,21 @@
+-  libsqlite3 >= 3.16.2
+
+-  GNU libunistring >= 0.9.3
+
+-  libcurl >= 7.26 (or libgnurl >= 7.26)
+
+-  libqrencode >= 4.0.0
+
+-  GNU libgcrypt >= 1.6
+
+-  libsodium >= 1.0
+
+-  libargon2 >= 20171227
+
+-  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/>`__)
diff --git a/doc/sphinx/frags/using-anastasis-config.rst b/doc/sphinx/frags/using-anastasis-config.rst
new file mode 100644
index 0000000..2c0a1ca
--- /dev/null
+++ b/doc/sphinx/frags/using-anastasis-config.rst
@@ -0,0 +1,50 @@
+Using anastasis-config
+----------------------
+
+The tool ``anastasis-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
+
+   $ anastasis-config -s $SECTION
+
+to list all of the configuration values in section ``$SECTION``.
+
+Run
+
+.. code-block:: console
+
+   $ anastasis-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
+
+   $ anastasis-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 ``anastasis-config``. For example,
+compare:
+
+.. code-block:: console
+
+   $ anastasis-config -s ACCOUNT-bank \
+                  -o WIRE_RESPONSE
+   $ anastasis-config -f -s ACCOUNT-bank \
+                  -o WIRE_RESPONSE
+
+While the configuration file is typically located at
+``$HOME/.config/taler.conf``, an alternative location can be specified
+to ``taler-merchant-httpd`` and ``anastasis-config`` using the ``-c``
+option.