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