taler-magnet-bank-manual.rst (8236B)
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 2.1, 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 You will need the latest version of the rust stable toolchain and a C toolchain: 63 64 .. code-block:: console 65 66 $ sudo apt install rustup build-essential 67 $ rustup toolchain install stable 68 69 Then from top-level run: 70 71 .. code-block:: console 72 73 $ ./bootstrap 74 75 To install the adapter as a Debian/Ubuntu package with an automated secure setup and systemd services: 76 77 .. code-block:: console 78 79 $ sudo apt install debhelper 80 $ make deb 81 $ sudo dpkg -i ../taler-magnet-bank*.deb 82 83 If the previous steps succeeded, the ``taler-magnet-bank`` command should be found in the $PATH. 84 85 Services, users, groups and file system hierarchy 86 ------------------------------------------------- 87 88 The *taler-magnet-bank* package will create several system users 89 to compartmentalize different parts of the system: 90 91 * ``taler-magnet-bank-httpd``: runs the HTTP daemon with the API logic. 92 * ``taler-magnet-bank-worker``: runs the worker daemon interacting with the Magnet Bank API. 93 * ``postgres``: runs the PostgreSQL database (from *postgresql* package). 94 95 The adapter setup uses the following system groups: 96 97 * ``taler-magnet-bank-db``: group for all adapter users with direct database access, specifically taler-magnet-bank-httpd and taler-magnet-bank-worker. 98 99 The package will deploy systemd service files in 100 ``/usr/lib/systemd/system/`` for the various components: 101 102 * ``taler-magnet-bank-httpd.service``: adapter REST API. 103 * ``taler-magnet-bank-httpd.socket``: systemd socket activation for the HTTP daemon. 104 * ``taler-magnet-bank-worker.service``: worker deamon interacting with the Magnet Bank API. 105 * ``taler-magnet-bank.target``: main target for the adapter to be operational. 106 107 The deployment creates the following key locations in the system: 108 109 * ``/etc/taler-magnet-bank/``: configuration files. 110 * ``/run/taler-magnet-bank/``: contains the UNIX domain sockets for inter-process communication (IPC). 111 * ``/var/lib/taler-magnet-bank/``: serves as the $HOME for taler-magnet-bank-worker and contains the Magnet Bank authentification tokens. 112 113 Configuration Fundamentals 114 ========================== 115 116 This chapter provides fundamental details about the adapter configuration. 117 118 The configuration for all adapter components uses a single configuration file 119 as entry point: ``/etc/taler-magnet-bank/taler-magnet-bank.conf``. 120 121 System defaults are automatically loaded from files in 122 ``/usr/share/taler-magnet-bank/config.d``. 123 These default files should never be modified. 124 125 The default configuration ``taler-magnet-bank.conf`` configuration file 126 also includes all configuration files in ``/etc/taler-magnet-bank/conf.d``. 127 The settings from files in 128 ``conf.d`` are only relevant to particular components of an adapter, while 129 ``taler-magnet-bank.conf`` contains settings that affect all adapter components. 130 131 132 The directory ``/etc/taler-magnet-bank/secrets`` contains configuration file snippets with 133 values that should only be readable to certain users. They are included with the ``@inline-secret@`` 134 directive and should end with ``.secret.conf``. 135 136 To view the entire configuration annotated with the source of each configuration option, you 137 can use the ``taler-magnet-bank config`` helper: 138 139 140 .. code-block:: shell-session 141 142 # taler-magnet-bank config dump --diagnostics 143 144 Basic Setup 145 =========== 146 147 Database setup 148 -------------- 149 150 The configuration file must include a connection string that tells the adapter how it should connect to the database. The default 151 is: 152 153 .. code-block:: ini 154 :caption: /etc/taler-magnet-bank/secrets/magnet-bank-db.secret.conf 155 156 [magnet-bankdb-postgres] 157 config = postgres:///taler-magnet-bank 158 159 If the database is run on a different host, please follow the instructions 160 from the PostgreSQL manual for configuring remote access. 161 162 Assuming the configuration is correct, the following 163 command initializes (or upgrades) the database schema using: 164 You can then use a script to automate a secure database setup: 165 166 .. code-block:: console 167 168 $ sudo taler-magnet-bank-dbconfig 169 170 Worker setup 171 ------------ 172 173 You will need a Magnet Bank account to sync. 174 Update the configuration files: 175 176 .. code-block:: ini 177 :caption: /etc/taler-magnet-bank/taler-magnet-bank.conf 178 179 [magnet-bank] 180 IBAN = HU59131000073585363679133532 181 NAME = John Smith S.A. 182 183 .. code-block:: ini 184 :caption: /etc/taler-magnet-bank/secrets/magnet-bank-worker.secret.conf 185 186 [magnet-bank-worker] 187 CONSUMER_KEY = $CONSUMER_KEY 188 CONSUMER_SECRET = $CONSUMER_SECRET 189 190 And finaly run the setup process: 191 192 .. code-block:: console 193 194 $ sudo -u taler-magnet-bank-worker taler-magnet-bank -c /etc/taler-magnet-bank/taler-magnet-bank.conf setup 195 196 Wire Gateway setup 197 ------------------ 198 199 Update the configuration files: 200 201 .. code-block:: ini 202 :caption: /etc/taler-magnet-bank/conf.d/magnet-bank-httpd.conf 203 204 [magnet-bank-httpd-wire-gateway-api] 205 ENABLED = YES 206 207 .. code-block:: ini 208 :caption: /etc/taler-magnet-bank/secrets/magnet-bank-httpd.secret.conf 209 210 [magnet-bank-httpd-wire-gateway-api 211 AUTH_METHOD = bearer 212 TOKEN = $SECRET_TOKEN 213 214 Check the server is correctly configured: 215 216 .. code-block:: console 217 218 $ sudo -u taler-magnet-bank-httpd taler-magnet-bank -c /etc/taler-magnet-bank/taler-magnet-bank.conf serve --check 219 220 Configuration 221 ============= 222 223 Here are some configuration you might want to change: 224 225 Worker frequency 226 ---------------- 227 228 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. 229 230 .. code-block:: ini 231 :caption: /etc/taler-magnet-bank/conf.d/magnet-bank-worker.conf 232 233 [magnet-bank-worker] 234 FREQUENCY = 3m 235 236 Deployment 237 ========== 238 239 This chapter describes how to deploy the adapter once the basic installation 240 and configuration are completed. 241 242 Reverse Proxy Setup 243 ------------------- 244 245 By default, the ``taler-magnet-bank-httpd`` service listens for HTTP connections 246 on a UNIX domain socket. To make the service publicly available, a reverse 247 proxy such as nginx should be used. We strongly recommend to configure nginx 248 to use TLS. 249 250 The ``taler-magnet-bank`` package ships with a sample configuration that can be 251 enabled in nginx: 252 253 .. code-block:: shell-session 254 255 # vim /etc/nginx/sites-available/taler-magnet-bank 256 < ... customize configuration ... > 257 # ln -s /etc/nginx/sites-available/taler-magnet-bank /etc/nginx/sites-enabled/taler-magnet-bank 258 # systemctl reload nginx 259 260 With this last step, we are finally ready to launch the 261 main adapter process. 262 263 Launching the adapter 264 --------------------- 265 266 .. code-block:: console 267 268 $ sudo systemctl start taler-magnet-bank.target