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