taler-magnet-bank-manual.rst (10491B)
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 .. contents:: Table of Contents 28 :depth: 1 29 :local: 30 31 Installation 32 ============ 33 34 Installing on Debian 35 -------------------- 36 37 .. include:: frags/installing-debian.rst 38 39 To install the adapter, you can now simply run: 40 41 .. code-block:: shell-session 42 43 # apt install taler-magnet-bank 44 45 Installing on Ubuntu 46 -------------------- 47 48 .. include:: frags/installing-ubuntu.rst 49 50 To install the adapter, you can now simply run: 51 52 .. code-block:: shell-session 53 54 # apt install taler-magnet-bank 55 56 Building from source 57 -------------------- 58 59 Magnet Bank Adapter belongs to the Taler Rust project, and can be downloaded via Git: 60 61 .. code-block:: console 62 63 $ git clone git://git.taler.net/taler-rust 64 $ cd taler-rust 65 66 You will need the latest version of the rust stable toolchain and a C toolchain: 67 68 .. code-block:: console 69 70 $ sudo apt install rustup build-essential 71 $ rustup toolchain install stable 72 73 Then from top-level run: 74 75 .. code-block:: console 76 77 $ ./bootstrap 78 79 Install deb package 80 ~~~~~~~~~~~~~~~~~~~ 81 82 To install the adapter as a Debian/Ubuntu package with an automated secure setup and systemd services: 83 84 .. code-block:: console 85 86 $ sudo apt install debhelper 87 $ make deb 88 $ sudo dpkg -i ../taler-magnet-bank*.deb 89 90 If the previous steps succeeded, the ``taler-magnet-bank`` command should be found in the $PATH. 91 92 Install binaries 93 ~~~~~~~~~~~~~~~~ 94 95 To install the adapter binaries and default configuration localy run: 96 97 .. code-block:: console 98 99 $ ./configure --prefix=$PREFIX 100 $ make install 101 102 If the previous steps succeeded, the ``taler-magnet-bank`` command should be found in the $PATH. 103 104 Services, users, groups and file system hierarchy 105 ------------------------------------------------- 106 107 The *taler-magnet-bank* package will create several system users 108 to compartmentalize different parts of the system: 109 110 * ``taler-magnet-bank-httpd``: runs the HTTP daemon with the API logic. 111 * ``taler-magnet-bank-worker``: runs the worker daemon interacting with the Magnet Bank API. 112 * ``postgres``: runs the PostgreSQL database (from *postgresql* package). 113 114 The adapter setup uses the following system groups: 115 116 * ``taler-magnet-bank-db``: group for all adapter users with direct database access, specifically taler-magnet-bank-httpd and taler-magnet-bank-worker. 117 118 The package will deploy systemd service files in 119 ``/usr/lib/systemd/system/`` for the various components: 120 121 * ``taler-magnet-bank-httpd.service``: adapter REST API. 122 * ``taler-magnet-bank-httpd.socket``: systemd socket activation for the HTTP daemon. 123 * ``taler-magnet-bank-worker.service``: worker deamon interacting with the Magnet Bank API. 124 * ``taler-magnet-bank.target``: main target for the adapter to be operational. 125 126 The deployment creates the following key locations in the system: 127 128 * ``/etc/taler-magnet-bank/``: configuration files. 129 * ``/run/taler-magnet-bank/``: contains the UNIX domain sockets for inter-process communication (IPC). 130 * ``/var/lib/taler-magnet-bank/``: serves as the $HOME for taler-magnet-bank-worker and contains the Magnet Bank authentification tokens. 131 132 Configuration Fundamentals 133 ========================== 134 135 This chapter provides fundamental details about the adapter configuration. 136 137 The configuration for all adapter components uses a single configuration file 138 as entry point: ``/etc/taler-magnet-bank/taler-magnet-bank.conf``. 139 140 System defaults are automatically loaded from files in 141 ``/usr/share/taler-magnet-bank/config.d``. 142 These default files should never be modified. 143 144 The default configuration ``taler-magnet-bank.conf`` configuration file 145 also includes all configuration files in ``/etc/taler-magnet-bank/conf.d``. 146 The settings from files in 147 ``conf.d`` are only relevant to particular components of an adapter, while 148 ``taler-magnet-bank.conf`` contains settings that affect all adapter components. 149 150 151 The directory ``/etc/taler-magnet-bank/secrets`` contains configuration file snippets with 152 values that should only be readable to certain users. They are included with the ``@inline-secret@`` 153 directive and should end with ``.secret.conf``. 154 155 To view the entire configuration annotated with the source of each configuration option, you 156 can use the ``taler-magnet-bank config`` helper: 157 158 159 .. code-block:: shell-session 160 161 # taler-magnet-bank config dump --diagnostics 162 163 .. include:: frags/configuration-format.rst 164 165 Basic Setup 166 =========== 167 168 Using package script 169 -------------------- 170 171 Database setup 172 ~~~~~~~~~~~~~~ 173 174 The configuration file must include a connection string that tells the adapter how it should connect to the database. The default 175 is: 176 177 .. code-block:: ini 178 :caption: /etc/taler-magnet-bank/secrets/magnet-bank-db.secret.conf 179 180 [magnet-bankdb-postgres] 181 config = postgres:///taler-magnet-bank 182 183 If the database is run on a different host, please follow the instructions 184 from the PostgreSQL manual for configuring remote access. 185 186 Assuming the configuration is correct, the following 187 command initializes (or upgrades) the database schema using: 188 You can then use a script to automate a secure database setup: 189 190 .. code-block:: console 191 192 $ sudo taler-magnet-bank-dbconfig 193 194 Worker setup 195 ~~~~~~~~~~~~ 196 197 You will need a Magnet Bank account to sync. 198 Update the configuration files: 199 200 .. code-block:: ini 201 :caption: /etc/taler-magnet-bank/taler-magnet-bank.conf 202 203 [magnet-bank] 204 IBAN = HU59131000073585363679133532 205 NAME = John Smith S.A. 206 207 .. code-block:: ini 208 :caption: /etc/taler-magnet-bank/secrets/magnet-bank-worker.secret.conf 209 210 [magnet-bank-worker] 211 CONSUMER_KEY = $CONSUMER_KEY 212 CONSUMER_SECRET = $CONSUMER_SECRET 213 214 And finaly run the setup process: 215 216 .. code-block:: console 217 218 $ sudo -u taler-magnet-bank-worker taler-magnet-bank -c /etc/taler-magnet-bank/taler-magnet-bank.conf setup 219 220 Wire Gateway setup 221 ~~~~~~~~~~~~~~~~~~ 222 223 Update the configuration files: 224 225 .. code-block:: ini 226 :caption: /etc/taler-magnet-bank/conf.d/magnet-bank-httpd.conf 227 228 [magnet-bank-httpd-wire-gateway-api] 229 ENABLED = YES 230 231 .. code-block:: ini 232 :caption: /etc/taler-magnet-bank/secrets/magnet-bank-httpd.secret.conf 233 234 [magnet-bank-httpd-wire-gateway-api 235 AUTH_METHOD = bearer 236 TOKEN = $SECRET_TOKEN 237 238 Check the server is correctly configured: 239 240 .. code-block:: console 241 242 $ sudo -u taler-magnet-bank-httpd taler-magnet-bank -c /etc/taler-magnet-bank/taler-magnet-bank.conf serve --check 243 244 Manual setup 245 ------------ 246 247 Database setup 248 ~~~~~~~~~~~~~~ 249 250 The configuration file must include a connection string that tells the adapter how it should connect to the database. The default 251 is: 252 253 .. code-block:: ini 254 :caption: $CONFIG_FILE 255 256 [magnet-bankdb-postgres] 257 config = postgres:///taler-magnet-bank 258 259 You must make sure that this database exists and is accessible to the user 260 running the adapter before continuing. If the database is run on a different host, please follow the instructions from the PostgreSQL manual for configuring remote access. 261 262 Assuming that the configuration file exists at ``$CONFIG_FILE``, the following 263 command initializes (or upgrades) the database schema: 264 265 .. code-block:: console 266 267 $ taler-magnet-bank -c "$CONFIG_FILE" dbinit 268 269 Update the configuration files: 270 271 .. code-block:: ini 272 :caption: $CONFIG_FILE 273 274 [magnet-bank] 275 IBAN = HU59131000073585363679133532 276 NAME = John Smith S.A. 277 278 [magnet-bank-worker] 279 CONSUMER_KEY = $CONSUMER_KEY 280 CONSUMER_SECRET = $CONSUMER_SECRET 281 282 And finaly run the setup process: 283 284 .. code-block:: console 285 286 $ taler-magnet-bank -c "$CONFIG_FILE" setup 287 288 Wire Gateway setup 289 ~~~~~~~~~~~~~~~~~~ 290 291 Update the configuration files: 292 293 .. code-block:: ini 294 :caption: $CONF_FILE 295 296 [magnet-bank-httpd-wire-gateway-api] 297 ENABLED = YES 298 AUTH_METHOD = bearer 299 TOKEN = $SECRET_TOKEN 300 301 Check the server is correctly configured: 302 303 .. code-block:: console 304 305 $ taler-magnet-bank -c "$CONF_FILE" serve --check 306 307 Deployment 308 ========== 309 310 This chapter describes how to deploy the adapter once the basic installation 311 and configuration are completed. 312 313 Serving 314 ------- 315 316 The adapter can serve HTTP over both TCP and UNIX domain socket. 317 318 The following options are to be configured in the section ``[magnet-bank-httpd]``: 319 320 - ``SERVE``: Must be set to ``tcp`` to serve HTTP over TCP, or ``unix`` to serve 321 HTTP over a UNIX domain socket. 322 323 - ``PORT``: Set to the TCP port to listen on if ``SERVE`` is ``tcp``. 324 325 - ``UNIXPATH``: Set to the UNIX domain socket path to listen on if ``SERVE`` is 326 ``unix``. 327 328 - ``UNIXPATH_MODE``: Number giving the mode with the access permission mask 329 for the ``UNIXPATH`` (i.e. 660 = ``rw-rw---``). Make sure to set it in such 330 a way that your adapter has permissions to access the UNIX domain 331 socket. The default (660) assumes that the reverse proxy is a member of 332 the group under which the adapter HTTP server is running. 333 334 Reverse Proxy Setup 335 ------------------- 336 337 By default, the ``taler-magnet-bank-httpd`` service listens for HTTP connections 338 on a UNIX domain socket. To make the service publicly available, a reverse 339 proxy such as nginx should be used. We strongly recommend to configure nginx 340 to use TLS. 341 342 The ``taler-magnet-bank`` package ships with a sample configuration that can be 343 enabled in nginx: 344 345 .. code-block:: shell-session 346 347 # vim /etc/nginx/sites-available/taler-magnet-bank 348 < ... customize configuration ... > 349 # ln -s /etc/nginx/sites-available/taler-magnet-bank /etc/nginx/sites-enabled/taler-magnet-bank 350 # systemctl reload nginx 351 352 With this last step, we are finally ready to launch the 353 main adapter process. 354 355 Launching the adapter 356 --------------------- 357 358 .. code-block:: console 359 360 $ sudo systemctl start taler-magnet-bank.target