taler-wise-manual.rst (9466B)
1 .. 2 This file is part of GNU TALER. 3 Copyright (C) 2026 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 @author Christian Grothoff 18 19 20 Wise Adapter Setup Manual 21 ########################### 22 23 taler-wise is a Wise Taler adapter. It allows running a GNU Taler exchange 24 on top of a core banking system provided by Wise, which is commonly 25 used for regional currencies. taler-wise implements the 26 taler-wire-gateway API, which is alternatively provided by the 27 :ref:`libeufin-bank <libeufin-bank>` (stand-alone), 28 :ref:`libeufin-nexus <libeufin-nexus>` (EBICS integration) or the 29 :ref:`Deploymerizer <depolymerization>` (for Bitcoin and Ethereum). 30 31 To use the adapter, you must setup an account for the GNU Taler exchange 32 in Wise and configure the adapter with the respective 33 credentials. Furthermore, you must point the GNU Taler exchange to the 34 taler-wise adapter as its taler-wire-gateway (and again provide the 35 necessary credentials). 36 37 Afterwards, taler-wise will inform your GNU Taler exchange about 38 transfers to the GNU Taler exchange account, 39 allowing users to withdraw digital cash by sending money. 40 41 This manual targets system administrators who want to install and 42 operate a Wise GNU Taler adapter. 43 44 .. warning:: 45 46 This adapter is read-only. It cannot perform transfer or bounce malformed transactions. 47 48 49 .. contents:: Table of Contents 50 :depth: 1 51 :local: 52 53 Installation 54 ============ 55 56 Installing on Debian 57 -------------------- 58 59 .. include:: frags/installing-debian.rst 60 61 To install the adapter, you can now simply run: 62 63 .. code-block:: shell-session 64 65 # apt install taler-wise 66 67 Installing on Ubuntu 68 -------------------- 69 70 .. include:: frags/installing-ubuntu.rst 71 72 To install the adapter, you can now simply run: 73 74 .. code-block:: shell-session 75 76 # apt install taler-wise 77 78 Building from source 79 -------------------- 80 81 Wise Adapter belongs to the Taler Rust project, and can be downloaded via Git: 82 83 .. code-block:: console 84 85 $ git clone git://git.taler.net/taler-rust 86 $ cd taler-rust 87 88 Building Debian/Ubuntu packages requires the distribution packages ``cargo`` 89 and ``rustc`` (version 1.95 or newer), as well as a C toolchain, Python and Git: 90 91 .. code-block:: console 92 93 $ sudo apt install cargo rustc build-essential python3 git debhelper 94 95 If your distribution provides an older ``rustc``, install newer distribution 96 packages before continuing. A toolchain installed only through ``rustup`` does 97 not satisfy the Debian package build dependencies. 98 99 Then from top-level run: 100 101 .. code-block:: console 102 103 $ ./bootstrap 104 105 To install the adapter as a Debian/Ubuntu package with an automated secure setup and systemd services: 106 107 .. code-block:: console 108 109 $ make deb 110 $ sudo dpkg -i ../taler-wise*.deb 111 112 If the previous steps succeeded, the ``taler-wise`` command should be found in the $PATH. 113 114 Services, users, groups and file system hierarchy 115 ------------------------------------------------- 116 117 The *taler-wise* package will create several system users 118 to compartmentalize different parts of the system: 119 120 * ``taler-wise-httpd``: runs the HTTP daemon with the API logic. 121 * ``taler-wise-worker``: runs the worker daemon interacting with the Wise API. 122 * ``postgres``: runs the PostgreSQL database (from *postgresql* package). 123 124 The adapter setup uses the following system groups: 125 126 * ``taler-wise-db``: group for all adapter users with direct database access, specifically taler-wise-httpd and taler-wise-worker. 127 128 The package will deploy systemd service files in 129 ``/usr/lib/systemd/system/`` for the various components: 130 131 * ``taler-wise-httpd.service``: adapter REST API. 132 * ``taler-wise-httpd.socket``: systemd socket activation for the HTTP daemon. 133 * ``taler-wise-worker.service``: worker daemon interacting with the Wise API. 134 * ``taler-wise.target``: main target for the adapter to be operational. 135 136 The deployment creates the following key locations in the system: 137 138 * ``/etc/taler-wise/``: configuration files. 139 * ``/run/taler-wise/``: contains the UNIX domain sockets for inter-process communication (IPC). 140 141 Configuration Fundamentals 142 ========================== 143 144 This chapter provides fundamental details about the adapter configuration. 145 146 The configuration for all adapter components uses a single configuration file 147 as entry point: ``/etc/taler-wise/taler-wise.conf``. 148 149 System defaults are automatically loaded from files in 150 ``/usr/share/taler-wise/config.d``. 151 These default files should never be modified. 152 153 The default configuration ``taler-wise.conf`` configuration file 154 also includes all configuration files in ``/etc/taler-wise/conf.d``. 155 The settings from files in 156 ``conf.d`` are only relevant to particular components of an adapter, while 157 ``taler-wise.conf`` contains settings that affect all adapter components. 158 159 160 The directory ``/etc/taler-wise/secrets`` contains configuration file snippets with 161 values that should only be readable to certain users. They are included with the ``@inline-secret@`` 162 directive and should end with ``.secret.conf``. 163 164 To view the entire configuration annotated with the source of each configuration option, you 165 can use the ``taler-wise config`` helper: 166 167 168 .. code-block:: shell-session 169 170 # taler-wise -c /etc/taler-wise/taler-wise.conf config dump --diagnostics 171 172 Basic Setup 173 =========== 174 175 Database setup 176 -------------- 177 178 The configuration file must include a connection string that tells the adapter how it should connect to the database. The default 179 is: 180 181 .. code-block:: ini 182 :caption: /etc/taler-wise/secrets/wise-db.secret.conf 183 184 [wisedb-postgres] 185 config = postgres:///taler-wise 186 187 For a local PostgreSQL installation, the following helper creates the database 188 and roles, initializes (or upgrades) the schema, and grants service access: 189 190 .. code-block:: console 191 192 # taler-wise-dbconfig 193 194 Worker setup 195 ------------ 196 197 You will need a Wise account to sync. 198 Update the configuration files: 199 200 .. code-block:: ini 201 :caption: /etc/taler-wise/secrets/wise-worker.secret.conf 202 203 [wise-worker] 204 TOKEN = 4e6a7a34-8f20-4376-912f-8c679b6b4fda 205 206 And then run the setup process: 207 208 .. code-block:: console 209 210 $ sudo -u taler-wise-worker taler-wise -c /etc/taler-wise/taler-wise.conf setup 211 212 The setup process should fail and provide you with the information needed to fill in the required Wise profile information: 213 214 .. code-block:: ini 215 :caption: /etc/taler-wise/taler-wise.conf 216 217 [wise] 218 NAME = John Smith S.A. 219 220 .. code-block:: ini 221 :caption: /etc/taler-wise/conf.d/wise-system.conf 222 223 [wise] 224 PROFILE_ID = 77620708 225 226 Run the setup command again. It should now report the available balances and 227 ask you to configure at least one. Use the IDs and account details it reports: 228 229 .. code-block:: ini 230 :caption: /etc/taler-wise/conf.d/wise-system.conf 231 232 [wise-balance-eur] 233 ID = 139524631 234 CURRENCY = EUR 235 PAYTO_TYPE = iban 236 IBAN = GB82WEST12345698765432 237 BIC = TRWIBEB1XXX 238 239 And finally run the setup process again: 240 241 .. code-block:: console 242 243 $ sudo -u taler-wise-worker taler-wise -c /etc/taler-wise/taler-wise.conf setup 244 245 On success, setup initializes synchronization state from each balance's creation 246 time. If it reports errors, correct the configuration and run it again. 247 ``setup --reset`` resets all synchronization cursors and schedules to rescan 248 from balance creation; it does not reset credentials. 249 250 Wire Gateway setup 251 ------------------ 252 253 Update the configuration files: 254 255 .. code-block:: ini 256 :caption: /etc/taler-wise/conf.d/wise-httpd.conf 257 258 [wise-httpd-wire-gateway-api] 259 ENABLED = YES 260 261 .. code-block:: ini 262 :caption: /etc/taler-wise/secrets/wise-httpd.secret.conf 263 264 [wise-httpd-wire-gateway-api] 265 AUTH_METHOD = bearer 266 TOKEN = $SECRET_TOKEN 267 268 Check the server is correctly configured: 269 270 .. code-block:: console 271 272 $ sudo -u taler-wise-httpd taler-wise -c /etc/taler-wise/taler-wise.conf serve --check 273 274 Deployment 275 ========== 276 277 This chapter describes how to deploy the adapter once the basic installation 278 and configuration are completed. 279 280 Reverse Proxy Setup 281 ------------------- 282 283 By default, the ``taler-wise-httpd`` service listens for HTTP connections 284 on a UNIX domain socket. To make the service publicly available, a reverse 285 proxy such as nginx should be used. We strongly recommend to configure nginx 286 to use TLS. 287 288 The ``taler-wise`` package ships with a sample configuration that can be 289 enabled in nginx: 290 291 .. code-block:: shell-session 292 293 # vim /etc/nginx/sites-available/taler-wise 294 < ... customize configuration ... > 295 # ln -s /etc/nginx/sites-available/taler-wise /etc/nginx/sites-enabled/taler-wise 296 # systemctl reload nginx 297 298 With this last step, we are finally ready to launch the 299 main adapter process. 300 301 Launching the adapter 302 --------------------- 303 304 .. code-block:: console 305 306 # systemctl enable --now taler-wise.target 307 308 Use adapter APIS 309 ---------------- 310 311 The adapter expose the :ref:`Adapter API <adapter-api>` for each configured balance prefixes by ``/balances/{BALANCE_ID}/``.