commit b1ee352f3762e6c241dd88bc39e96797b4fc194d
parent 2da8359a9003b36a216912c2a430fe3aa980bf2a
Author: Antoine A <>
Date: Wed, 19 Nov 2025 12:44:56 +0100
magnet-bank: update doc
Diffstat:
3 files changed, 122 insertions(+), 7 deletions(-)
diff --git a/taler-developer-manual.rst b/taler-developer-manual.rst
@@ -47,6 +47,8 @@ overview:
used by banks in the EU. Allows an exchange to interact with
European banks.
+* taler-magnet-bank: implementation of the "bank" API using the Magnet Bank API.Allows an exchange to interact with Magnet Bank.
+
* depolymerization: implementation of the "bank" API on top of
blockchains, specifically Bitcoin and Ethereum. Allows an exchange
to interact with crypto-currencies.
diff --git a/taler-exchange-manual.rst b/taler-exchange-manual.rst
@@ -177,7 +177,9 @@ components:
(2) For production, **libeufin**'s ``libeufin-nexus`` component
implements a wire adapter towards the traditional SEPA banking
system with IBAN accounts using the EBICS protocol.
- (3) To use GNU Taler with blockchains, the **Depolymerization**
+ (3) For production, **talet-magnet-bank** component
+ implements a wire adapter towards the Magnet Bank API.
+ (4) To use GNU Taler with blockchains, the **Depolymerization**
component provides a wire gateway API that runs on top of
blockchains like Bitcoin and Ethereum.
diff --git a/taler-magnet-bank-manual.rst b/taler-magnet-bank-manual.rst
@@ -21,13 +21,15 @@ Magnet Bank Adapter Setup Manual
taler-magnet-bank is a Magnet Bank Taler adapter.
-In this manual, we explain how to setup an adapter.
+This manual targets system administrators who want to install and
+operate a Magnet Bank GNU Taler adapter
.. contents:: Table of Contents
+ :depth: 1
:local:
-Installing Adapter
-==================
+Installation
+============
Building from source
--------------------
@@ -77,8 +79,69 @@ To install the adapter binaries and default configuration localy run:
If the previous steps succeeded, the ``taler-magnet-bank`` command should be found in the $PATH.
-Adapter Setup
-=============
+Services, users, groups and file system hierarchy
+-------------------------------------------------
+
+The *taler-magnet-bank* package will create several system users
+to compartmentalize different parts of the system:
+
+* ``taler-magnet-bank-httpd``: runs the HTTP daemon with the API logic.
+* ``taler-magnet-bank-worker``: runs the worker daemon interacting with the Magnet Bank API.
+* ``postgres``: runs the PostgreSQL database (from *postgresql* package).
+
+The adapter setup uses the following system groups:
+
+* ``taler-magnet-bank-db``: group for all adapter users with direct database access, specifically taler-magnet-bank-httpd and taler-magnet-bank-worker.
+
+The package will deploy systemd service files in
+``/usr/lib/systemd/system/`` for the various components:
+
+* ``taler-magnet-bank-httpd.service``: adapter REST API.
+* ``taler-magnet-bank-httpd.socket``: systemd socket activation for the HTTP daemon.
+* ``taler-magnet-bank-worker.service``: worker deamon interacting with the Magnet Bank API.
+* ``taler-magnet-bank.target``: main target for the adapter to be operational.
+
+The deployment creates the following key locations in the system:
+
+* ``/etc/taler-magnet-bank/``: configuration files.
+* ``/run/taler-magnet-bank/``: contains the UNIX domain sockets for inter-process communication (IPC).
+* ``/var/lib/taler-magnet-bank/``: serves as the $HOME for taler-magnet-bank-worker and contains the Magnet Bank authentification tokens.
+
+Configuration Fundamentals
+==========================
+
+This chapter provides fundamental details about the adapter configuration.
+
+The configuration for all adapter components uses a single configuration file
+as entry point: ``/etc/taler-magnet-bank/taler-magnet-bank.conf``.
+
+System defaults are automatically loaded from files in
+``/usr/share/taler-magnet-bank/config.d``.
+These default files should never be modified.
+
+The default configuration ``taler-magnet-bank.conf`` configuration file
+also includes all configuration files in ``/etc/taler-magnet-bank/conf.d``.
+The settings from files in
+``conf.d`` are only relevant to particular components of an adapter, while
+``taler-magnet-bank.conf`` contains settings that affect all adapter components.
+
+
+The directory ``/etc/taler-magnet-bank/secrets`` contains configuration file snippets with
+values that should only be readable to certain users. They are included with the ``@inline-secret@``
+directive and should end with ``.secret.conf``.
+
+To view the entire configuration annotated with the source of each configuration option, you
+can use the ``taler-magnet-bank config`` helper:
+
+
+.. code-block:: shell-session
+
+ # taler-magnet-bank config dump --diagnostics
+
+.. include:: frags/configuration-format.rst
+
+Basic Setup
+===========
Using package script
--------------------
@@ -156,7 +219,7 @@ Check the server is correctly configured:
$ sudo -u taler-magnet-bank-httpd taler-magnet-bank -c /etc/taler-magnet-bank/taler-magnet-bank.conf serve --check
-Simple setup
+Manual setup
------------
Database setup
@@ -222,6 +285,54 @@ Check the server is correctly configured:
Deployment
==========
+This chapter describes how to deploy the adapter once the basic installation
+and configuration are completed.
+
+Serving
+-------
+
+The adapter can serve HTTP over both TCP and UNIX domain socket.
+
+The following options are to be configured in the section ``[magnet-bank-httpd]``:
+
+- ``SERVE``: Must be set to ``tcp`` to serve HTTP over TCP, or ``unix`` to serve
+ HTTP over a UNIX domain socket.
+
+- ``PORT``: Set to the TCP port to listen on if ``SERVE`` is ``tcp``.
+
+- ``UNIXPATH``: Set to the UNIX domain socket path to listen on if ``SERVE`` is
+ ``unix``.
+
+- ``UNIXPATH_MODE``: Number giving the mode with the access permission mask
+ for the ``UNIXPATH`` (i.e. 660 = ``rw-rw---``). Make sure to set it in such
+ a way that your adapter has permissions to access the UNIX domain
+ socket. The default (660) assumes that the reverse proxy is a member of
+ the group under which the adapter HTTP server is running.
+
+Reverse Proxy Setup
+-------------------
+
+By default, the ``taler-magnet-bank-httpd`` service listens for HTTP connections
+on a UNIX domain socket. To make the service publicly available, a reverse
+proxy such as nginx should be used. We strongly recommend to configure nginx
+to use TLS.
+
+The ``taler-magnet-bank`` package ships with a sample configuration that can be
+enabled in nginx:
+
+.. code-block:: shell-session
+
+ # vim /etc/nginx/sites-available/taler-magnet-bank
+ < ... customize configuration ... >
+ # ln -s /etc/nginx/sites-available/taler-magnet-bank /etc/nginx/sites-enabled/taler-magnet-bank
+ # systemctl reload nginx
+
+With this last step, we are finally ready to launch the
+main adapter process.
+
+Launching an adapter
+---------------------
+
.. code-block:: console
$ sudo systemctl start taler-magnet-bank.target
\ No newline at end of file
