taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

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}/``.