taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

taler-magnet-bank-manual.rst (8380B)


      1 ..
      2   This file is part of GNU TALER.
      3   Copyright (C) 2025 Taler Systems SA
      4 
      5   TALER is free software; you can redistribute it and/or modify it under the
      6   terms of the GNU Affero General Public License as published by the Free Software
      7   Foundation; either version 3.0, or (at your option) any later version.
      8 
      9   TALER is distributed in the hope that it will be useful, but WITHOUT ANY
     10   WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
     11   A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details.
     12 
     13   You should have received a copy of the GNU Affero General Public License along with
     14   TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
     15 
     16   @author Antoine d'Aligny
     17 
     18 
     19 Magnet Bank Adapter Setup Manual
     20 ################################
     21 
     22 taler-magnet-bank is a Magnet Bank Taler adapter.
     23 
     24 This manual targets system administrators who want to install and
     25 operate a Magnet Bank GNU Taler adapter
     26 
     27 Installation
     28 ============
     29 
     30 Installing on Debian
     31 --------------------
     32 
     33 .. include:: frags/installing-debian.rst
     34 
     35 To install the adapter, you can now simply run:
     36 
     37 .. code-block:: shell-session
     38 
     39   # apt install taler-magnet-bank
     40 
     41 Installing on Ubuntu
     42 --------------------
     43 
     44 .. include:: frags/installing-ubuntu.rst
     45 
     46 To install the adapter, you can now simply run:
     47 
     48 .. code-block:: shell-session
     49 
     50   # apt install taler-magnet-bank
     51 
     52 Building from source
     53 --------------------
     54 
     55 Magnet Bank Adapter belongs to the Taler Rust project, and can be downloaded via Git:
     56 
     57 .. code-block:: console
     58 
     59   $ git clone git://git.taler.net/taler-rust
     60   $ cd taler-rust
     61 
     62 Building Debian/Ubuntu packages requires the distribution packages ``cargo``
     63 and ``rustc`` (version 1.95 or newer), as well as a C toolchain, Python and Git:
     64 
     65 .. code-block:: console
     66 
     67   $ sudo apt install cargo rustc build-essential python3 git debhelper
     68 
     69 If your distribution provides an older ``rustc``, install newer distribution
     70 packages before continuing. A toolchain installed only through ``rustup`` does
     71 not satisfy the Debian package build dependencies.
     72 
     73 Then from top-level run:
     74 
     75 .. code-block:: console
     76 
     77   $ ./bootstrap
     78 
     79 To install the adapter as a Debian/Ubuntu package with an automated secure setup and systemd services:
     80 
     81 .. code-block:: console
     82 
     83   $ make deb
     84   $ sudo dpkg -i ../taler-magnet-bank*.deb
     85 
     86 If the previous steps succeeded, the ``taler-magnet-bank`` command should be found in the $PATH.
     87 
     88 Services, users, groups and file system hierarchy
     89 -------------------------------------------------
     90 
     91 The *taler-magnet-bank* package will create several system users
     92 to compartmentalize different parts of the system:
     93 
     94 * ``taler-magnet-bank-httpd``: runs the HTTP daemon with the API logic.
     95 * ``taler-magnet-bank-worker``: runs the worker daemon interacting with the Magnet Bank API.
     96 * ``postgres``: runs the PostgreSQL database (from *postgresql* package).
     97 
     98 The adapter setup uses the following system groups:
     99 
    100 * ``taler-magnet-bank-db``: group for all adapter users with direct database access, specifically taler-magnet-bank-httpd and taler-magnet-bank-worker.
    101 
    102 The package will deploy systemd service files in
    103 ``/usr/lib/systemd/system/`` for the various components:
    104 
    105 * ``taler-magnet-bank-httpd.service``: adapter REST API.
    106 * ``taler-magnet-bank-httpd.socket``: systemd socket activation for the HTTP daemon.
    107 * ``taler-magnet-bank-worker.service``: worker daemon interacting with the Magnet Bank API.
    108 * ``taler-magnet-bank.target``: main target for the adapter to be operational.
    109 
    110 The deployment creates the following key locations in the system:
    111 
    112 * ``/etc/taler-magnet-bank/``: configuration files.
    113 * ``/run/taler-magnet-bank/``: contains the UNIX domain sockets for inter-process communication (IPC).
    114 * ``/var/lib/taler-magnet-bank/``: serves as the $HOME for taler-magnet-bank-worker and contains the Magnet Bank authentification tokens.
    115 
    116 Configuration Fundamentals
    117 ==========================
    118 
    119 This chapter provides fundamental details about the adapter configuration.
    120 
    121 The configuration for all adapter components uses a single configuration file
    122 as entry point: ``/etc/taler-magnet-bank/taler-magnet-bank.conf``.
    123 
    124 System defaults are automatically loaded from files in
    125 ``/usr/share/taler-magnet-bank/config.d``.
    126 These default files should never be modified.
    127 
    128 The default configuration ``taler-magnet-bank.conf`` configuration file
    129 also includes all configuration files in ``/etc/taler-magnet-bank/conf.d``.
    130 The settings from files in
    131 ``conf.d`` are only relevant to particular components of an adapter, while
    132 ``taler-magnet-bank.conf`` contains settings that affect all adapter components.
    133 
    134 
    135 The directory ``/etc/taler-magnet-bank/secrets`` contains configuration file snippets with
    136 values that should only be readable to certain users.  They are included with the ``@inline-secret@``
    137 directive and should end with ``.secret.conf``.
    138 
    139 To view the entire configuration annotated with the source of each configuration option, you
    140 can use the ``taler-magnet-bank config`` helper:
    141 
    142 
    143 .. code-block:: shell-session
    144 
    145   # taler-magnet-bank -c /etc/taler-magnet-bank/taler-magnet-bank.conf config dump --diagnostics
    146 
    147 Basic Setup
    148 ===========
    149 
    150 Database setup
    151 --------------
    152 
    153 The configuration file must include a connection string that tells the adapter how it should connect to the database. The default
    154 is:
    155 
    156 .. code-block:: ini
    157   :caption: /etc/taler-magnet-bank/secrets/magnet-bank-db.secret.conf
    158 
    159   [magnet-bankdb-postgres]
    160   config = postgres:///taler-magnet-bank
    161 
    162 For a local PostgreSQL installation, the following helper creates the database
    163 and roles, initializes (or upgrades) the schema, and grants service access:
    164 
    165 .. code-block:: console
    166 
    167   $ sudo taler-magnet-bank-dbconfig
    168 
    169 Worker setup
    170 ------------
    171 
    172 You will need a Magnet Bank account to sync.
    173 Update the configuration files:
    174 
    175 .. code-block:: ini
    176   :caption: /etc/taler-magnet-bank/taler-magnet-bank.conf
    177 
    178   [magnet-bank]
    179   IBAN = HU30162000031000163100000000
    180   NAME = John Smith S.A.
    181 
    182 .. code-block:: ini
    183   :caption: /etc/taler-magnet-bank/secrets/magnet-bank-worker.secret.conf
    184 
    185   [magnet-bank-worker]
    186   CONSUMER_KEY = $CONSUMER_KEY
    187   CONSUMER_SECRET = $CONSUMER_SECRET
    188 
    189 And finally run the setup process:
    190 
    191 .. code-block:: console
    192 
    193   $ sudo -u taler-magnet-bank-worker taler-magnet-bank -c /etc/taler-magnet-bank/taler-magnet-bank.conf setup
    194 
    195 Wire Gateway setup
    196 ------------------
    197 
    198 Update the configuration files:
    199 
    200 .. code-block:: ini
    201   :caption: /etc/taler-magnet-bank/conf.d/magnet-bank-httpd.conf
    202 
    203   [magnet-bank-httpd-wire-gateway-api]
    204   ENABLED = YES
    205 
    206 .. code-block:: ini
    207   :caption: /etc/taler-magnet-bank/secrets/magnet-bank-httpd.secret.conf
    208 
    209   [magnet-bank-httpd-wire-gateway-api]
    210   AUTH_METHOD = bearer
    211   TOKEN = $SECRET_TOKEN
    212 
    213 Check the server is correctly configured:
    214 
    215 .. code-block:: console
    216 
    217   $ sudo -u taler-magnet-bank-httpd taler-magnet-bank -c /etc/taler-magnet-bank/taler-magnet-bank.conf serve --check
    218 
    219 Configuration
    220 =============
    221 
    222 Here are some configuration you might want to change:
    223 
    224 Worker frequency
    225 ----------------
    226 
    227 The worker runs periodically to index the bank history and initiate payments. It is best to run the worker often to make withdrawal faster but keep in mind that a very high frequency can place a significant load on your network provider.
    228 
    229 .. code-block:: ini
    230   :caption: /etc/taler-magnet-bank/conf.d/magnet-bank-worker.conf
    231 
    232   [magnet-bank-worker]
    233   FREQUENCY = 3m
    234 
    235 Deployment
    236 ==========
    237 
    238 This chapter describes how to deploy the adapter once the basic installation
    239 and configuration are completed.
    240 
    241 Reverse Proxy Setup
    242 -------------------
    243 
    244 By default, the ``taler-magnet-bank-httpd`` service listens for HTTP connections
    245 on a UNIX domain socket.  To make the service publicly available, a reverse
    246 proxy such as nginx should be used.  We strongly recommend to configure nginx
    247 to use TLS.
    248 
    249 The ``taler-magnet-bank`` package ships with a sample configuration that can be
    250 enabled in nginx:
    251 
    252 .. code-block:: shell-session
    253 
    254   # vim /etc/nginx/sites-available/taler-magnet-bank
    255   < ... customize configuration ... >
    256   # ln -s /etc/nginx/sites-available/taler-magnet-bank /etc/nginx/sites-enabled/taler-magnet-bank
    257   # systemctl reload nginx
    258 
    259 With this last step, we are finally ready to launch the
    260 main adapter process.
    261 
    262 Launching the adapter
    263 ---------------------
    264 
    265 .. code-block:: console
    266 
    267   $ sudo systemctl enable --now taler-magnet-bank.target