taler-wise-manual.rst (9131B)
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 Cyclos 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 You will need the latest version of the rust stable toolchain and a C toolchain: 89 90 .. code-block:: console 91 92 $ sudo apt install rustup build-essential 93 $ rustup toolchain install stable 94 95 Then from top-level run: 96 97 .. code-block:: console 98 99 $ ./bootstrap 100 101 To install the adapter as a Debian/Ubuntu package with an automated secure setup and systemd services: 102 103 .. code-block:: console 104 105 $ sudo apt install debhelper 106 $ make deb 107 $ sudo dpkg -i ../taler-wise*.deb 108 109 If the previous steps succeeded, the ``taler-wise`` command should be found in the $PATH. 110 111 Services, users, groups and file system hierarchy 112 ------------------------------------------------- 113 114 The *taler-wise* package will create several system users 115 to compartmentalize different parts of the system: 116 117 * ``taler-wise-httpd``: runs the HTTP daemon with the API logic. 118 * ``taler-wise-worker``: runs the worker daemon interacting with the Wise API. 119 * ``postgres``: runs the PostgreSQL database (from *postgresql* package). 120 121 The adapter setup uses the following system groups: 122 123 * ``taler-wise-db``: group for all adapter users with direct database access, specifically taler-wise-httpd and taler-wise-worker. 124 125 The package will deploy systemd service files in 126 ``/usr/lib/systemd/system/`` for the various components: 127 128 * ``taler-wise-httpd.service``: adapter REST API. 129 * ``taler-wise-httpd.socket``: systemd socket activation for the HTTP daemon. 130 * ``taler-wise-worker.service``: worker daemon interacting with the Wise API. 131 * ``taler-wise.target``: main target for the adapter to be operational. 132 133 The deployment creates the following key locations in the system: 134 135 * ``/etc/taler-wise/``: configuration files. 136 * ``/run/taler-wise/``: contains the UNIX domain sockets for inter-process communication (IPC). 137 138 Configuration Fundamentals 139 ========================== 140 141 This chapter provides fundamental details about the adapter configuration. 142 143 The configuration for all adapter components uses a single configuration file 144 as entry point: ``/etc/taler-cyclos/taler-wise.conf``. 145 146 System defaults are automatically loaded from files in 147 ``/usr/share/taler-wise/config.d``. 148 These default files should never be modified. 149 150 The default configuration ``taler-wise.conf`` configuration file 151 also includes all configuration files in ``/etc/taler-wise/conf.d``. 152 The settings from files in 153 ``conf.d`` are only relevant to particular components of an adapter, while 154 ``taler-wise.conf`` contains settings that affect all adapter components. 155 156 157 The directory ``/etc/taler-wise/secrets`` contains configuration file snippets with 158 values that should only be readable to certain users. They are included with the ``@inline-secret@`` 159 directive and should end with ``.secret.conf``. 160 161 To view the entire configuration annotated with the source of each configuration option, you 162 can use the ``taler-wise config`` helper: 163 164 165 .. code-block:: shell-session 166 167 # taler-wise config dump --diagnostics 168 169 Basic Setup 170 =========== 171 172 Database setup 173 -------------- 174 175 The configuration file must include a connection string that tells the adapter how it should connect to the database. The default 176 is: 177 178 .. code-block:: ini 179 :caption: /etc/taler-wise/secrets/wise-db.secret.conf 180 181 [wisedb-postgres] 182 config = postgres:///taler-wise 183 184 If the database is run on a different host, please follow the instructions 185 from the PostgreSQL manual for configuring remote access. 186 187 Assuming the configuration is correct, the following 188 command initializes (or upgrades) the database schema using: 189 You can then use a script to automate a secure database setup: 190 191 .. code-block:: console 192 193 # taler-wise-dbconfig 194 195 Worker setup 196 ------------ 197 198 You will need a Wise account to sync. 199 Update the configuration files: 200 201 .. code-block:: ini 202 :caption: /etc/taler-wise/secrets/wise-worker.secret.conf 203 204 [wise-worker] 205 TOKEN = 4e6a7a34-8f20-4376-912f-8c679b6b4fda 206 207 And then run the setup process: 208 209 .. code-block:: console 210 211 $ sudo -u taler-wise-worker taler-wise -c /etc/taler-wise/taler-wise.conf setup 212 213 The setup process should fail and provide you with the information needed to fill in the required Wise profile information: 214 215 .. code-block:: ini 216 :caption: /etc/taler-wise/taler-wise.conf 217 218 [wise] 219 NAME = John Smith S.A. 220 221 .. code-block:: ini 222 :caption: /etc/taler-wise/conf.d/wise-worker.conf 223 224 [wise-worker] 225 PROFILE_ID = 77620708 226 227 The setup process should fail and provide you with the information needed to fill the Wise balances information: 228 229 .. code-block:: ini 230 :caption: /etc/taler-wise/conf.d/wise-worker.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 This time, you should not see any errors; if you do, you should modify the configuration until it works. 246 247 Wire Gateway setup 248 ------------------ 249 250 Update the configuration files: 251 252 .. code-block:: ini 253 :caption: /etc/taler-wise/conf.d/wise-httpd.conf 254 255 [wise-httpd-wire-gateway-api] 256 ENABLED = YES 257 258 .. code-block:: ini 259 :caption: /etc/taler-wise/secrets/wise-httpd.secret.conf 260 261 [wise-httpd-wire-gateway-api] 262 AUTH_METHOD = bearer 263 TOKEN = $SECRET_TOKEN 264 265 Check the server is correctly configured: 266 267 .. code-block:: console 268 269 $ sudo -u taler-wise-httpd taler-wise -c /etc/taler-wise/taler-wise.conf serve --check 270 271 Deployment 272 ========== 273 274 This chapter describes how to deploy the adapter once the basic installation 275 and configuration are completed. 276 277 Reverse Proxy Setup 278 ------------------- 279 280 By default, the ``taler-wise-httpd`` service listens for HTTP connections 281 on a UNIX domain socket. To make the service publicly available, a reverse 282 proxy such as nginx should be used. We strongly recommend to configure nginx 283 to use TLS. 284 285 The ``taler-wise`` package ships with a sample configuration that can be 286 enabled in nginx: 287 288 .. code-block:: shell-session 289 290 # vim /etc/nginx/sites-available/taler-wise 291 < ... customize configuration ... > 292 # ln -s /etc/nginx/sites-available/taler-wise /etc/nginx/sites-enabled/taler-wise 293 # systemctl reload nginx 294 295 With this last step, we are finally ready to launch the 296 main adapter process. 297 298 Launching the adapter 299 --------------------- 300 301 .. code-block:: console 302 303 # systemctl enable --now taler-wise.target 304 305 Use adapter APIS 306 ---------------- 307 308 The adapter expose the :ref:`Adapter API <adapter-api>` for each configured balance prefixes by ``/balances/{BALANCE_ID}/``.