taler-docs

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

taler-cyclos-manual.rst (10348B)


      1 ..
      2   This file is part of GNU TALER.
      3   Copyright (C) 2025, 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 Cyclos Adapter Setup Manual
     21 ###########################
     22 
     23 taler-cyclos is a Cyclos Taler adapter. It allows running a GNU Taler exchange
     24 on top of a core banking system provided by Cyclos, which is commonly
     25 used for regional currencies. taler-cyclos 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-cyclos.png
     32 
     33 
     34 To use the adapter, you must setup an account for the GNU Taler exchange
     35 in your Cyclos system and configure the adapter with the respective
     36 credentials. Furthermore, you must point the GNU Taler exchange to the
     37 taler-cyclos adapter as its taler-wire-gateway (and again provide the
     38 necessary credentials).
     39 
     40 Afterwards, taler-cyclos will inform your GNU Taler exchange about
     41 wire transfers made within Cyclos to the GNU Taler exchange account,
     42 allowing users to withdraw digital cash by sending money in Cyclos
     43 to the GNU Taler exchange account. Similarly, when a merchant receives
     44 payments via the GNU Taler exchange, the GNU Taler exchange will use
     45 the taler-cyclos adapter to send funds from its Cyclos account to
     46 the merchant's Cyclos account.
     47 
     48 As a result, you can use GNU Taler as a digital cash payment system
     49 on top of any regional currency using Cyclos.
     50 
     51 This manual targets system administrators who want to install and
     52 operate a Cyclos GNU Taler adapter.
     53 
     54 
     55 .. contents:: Table of Contents
     56   :depth: 1
     57   :local:
     58 
     59 Installation
     60 ============
     61 
     62 Installing on Debian
     63 --------------------
     64 
     65 .. include:: frags/installing-debian.rst
     66 
     67 To install the adapter, you can now simply run:
     68 
     69 .. code-block:: shell-session
     70 
     71   # apt install taler-cyclos
     72 
     73 Installing on Ubuntu
     74 --------------------
     75 
     76 .. include:: frags/installing-ubuntu.rst
     77 
     78 To install the adapter, you can now simply run:
     79 
     80 .. code-block:: shell-session
     81 
     82   # apt install taler-cyclos
     83 
     84 Building from source
     85 --------------------
     86 
     87 Cyclos Adapter belongs to the Taler Rust project, and can be downloaded via Git:
     88 
     89 .. code-block:: console
     90 
     91   $ git clone git://git.taler.net/taler-rust
     92   $ cd taler-rust
     93 
     94 Building Debian/Ubuntu packages requires the distribution packages ``cargo``
     95 and ``rustc`` (version 1.95 or newer), as well as a C toolchain, Python and Git:
     96 
     97 .. code-block:: console
     98 
     99   $ sudo apt install cargo rustc build-essential python3 git debhelper
    100 
    101 If your distribution provides an older ``rustc``, install newer distribution
    102 packages before continuing. A toolchain installed only through ``rustup`` does
    103 not satisfy the Debian package build dependencies.
    104 
    105 Then from top-level run:
    106 
    107 .. code-block:: console
    108 
    109   $ ./bootstrap
    110 
    111 To install the adapter as a Debian/Ubuntu package with an automated secure setup and systemd services:
    112 
    113 .. code-block:: console
    114 
    115   $ make deb
    116   $ sudo dpkg -i ../taler-cyclos*.deb
    117 
    118 If the previous steps succeeded, the ``taler-cyclos`` command should be found in the $PATH.
    119 
    120 Services, users, groups and file system hierarchy
    121 -------------------------------------------------
    122 
    123 The *taler-cyclos* package will create several system users
    124 to compartmentalize different parts of the system:
    125 
    126 * ``taler-cyclos-httpd``: runs the HTTP daemon with the API logic.
    127 * ``taler-cyclos-worker``: runs the worker daemon interacting with the Cyclos API.
    128 * ``postgres``: runs the PostgreSQL database (from *postgresql* package).
    129 
    130 The adapter setup uses the following system groups:
    131 
    132 * ``taler-cyclos-db``: group for all adapter users with direct database access, specifically taler-cyclos-httpd and taler-cyclos-worker.
    133 
    134 The package will deploy systemd service files in
    135 ``/usr/lib/systemd/system/`` for the various components:
    136 
    137 * ``taler-cyclos-httpd.service``: adapter REST API.
    138 * ``taler-cyclos-httpd.socket``: systemd socket activation for the HTTP daemon.
    139 * ``taler-cyclos-worker.service``: worker daemon interacting with the Cyclos API.
    140 * ``taler-cyclos.target``: main target for the adapter to be operational.
    141 
    142 The deployment creates the following key locations in the system:
    143 
    144 * ``/etc/taler-cyclos/``: configuration files.
    145 * ``/run/taler-cyclos/``: contains the UNIX domain sockets for inter-process communication (IPC).
    146 
    147 Configuration Fundamentals
    148 ==========================
    149 
    150 This chapter provides fundamental details about the adapter configuration.
    151 
    152 The configuration for all adapter components uses a single configuration file
    153 as entry point: ``/etc/taler-cyclos/taler-cyclos.conf``.
    154 
    155 System defaults are automatically loaded from files in
    156 ``/usr/share/taler-cyclos/config.d``.
    157 These default files should never be modified.
    158 
    159 The default configuration ``taler-cyclos.conf`` configuration file
    160 also includes all configuration files in ``/etc/taler-cyclos/conf.d``.
    161 The settings from files in
    162 ``conf.d`` are only relevant to particular components of an adapter, while
    163 ``taler-cyclos.conf`` contains settings that affect all adapter components.
    164 
    165 
    166 The directory ``/etc/taler-cyclos/secrets`` contains configuration file snippets with
    167 values that should only be readable to certain users.  They are included with the ``@inline-secret@``
    168 directive and should end with ``.secret.conf``.
    169 
    170 To view the entire configuration annotated with the source of each configuration option, you
    171 can use the ``taler-cyclos config`` helper:
    172 
    173 
    174 .. code-block:: shell-session
    175 
    176   # taler-cyclos -c /etc/taler-cyclos/taler-cyclos.conf config dump --diagnostics
    177 
    178 Basic Setup
    179 ===========
    180 
    181 Database setup
    182 --------------
    183 
    184 The configuration file must include a connection string that tells the adapter how it should connect to the database. The default
    185 is:
    186 
    187 .. code-block:: ini
    188   :caption: /etc/taler-cyclos/secrets/cyclos-db.secret.conf
    189 
    190   [cyclosdb-postgres]
    191   config = postgres:///taler-cyclos
    192 
    193 For a local PostgreSQL installation, the following helper creates the database
    194 and roles, initializes (or upgrades) the schema, and grants service access:
    195 
    196 .. code-block:: console
    197 
    198   # taler-cyclos-dbconfig
    199 
    200 Worker setup
    201 ------------
    202 
    203 You will need a Cyclos account to sync.
    204 Update the configuration files:
    205 
    206 .. code-block:: ini
    207   :caption: /etc/taler-cyclos/taler-cyclos.conf
    208 
    209   [cyclos]
    210   CURRENCY = KUDOS
    211   CYCLOS_URL = https://demo.cyclos.org/
    212 
    213 .. code-block:: ini
    214   :caption: /etc/taler-cyclos/secrets/cyclos-worker.secret.conf
    215 
    216   [cyclos-worker]
    217   USERNAME = admin
    218   PASSWORD = password
    219 
    220 And then run the setup process:
    221 
    222 .. code-block:: console
    223 
    224   $ sudo -u taler-cyclos-worker taler-cyclos -c /etc/taler-cyclos/taler-cyclos.conf setup
    225 
    226 If the previous command failed with an ``inaccessibleChannel`` you will have to enable the ``Web services`` channel in your account settings. If this channel is disabled, you should contact the network administrators.
    227 
    228 The setup process should fail and provide you with the information needed to fill in the required Cyclos IDs:
    229 
    230 .. code-block:: ini
    231   :caption: /etc/taler-cyclos/taler-cyclos.conf
    232 
    233   [cyclos]
    234   ACCOUNT_ID = 7762070814178012479
    235   NAME = John Smith S.A.
    236 
    237 .. code-block:: ini
    238   :caption: /etc/taler-cyclos/conf.d/cyclos-worker.conf
    239 
    240   [cyclos-worker]
    241   ACCOUNT_TYPE_ID = 7762070814178012479
    242   PAYMENT_TYPE_ID = 7762070814178012479
    243 
    244 And finally run the setup process again:
    245 
    246 .. code-block:: console
    247 
    248   $ sudo -u taler-cyclos-worker taler-cyclos -c /etc/taler-cyclos/taler-cyclos.conf setup
    249 
    250 This time, you should not see any errors; if you do, you should modify the configuration until it works.
    251 
    252 Wire Gateway setup
    253 ------------------
    254 
    255 Update the configuration files:
    256 
    257 .. code-block:: ini
    258   :caption: /etc/taler-cyclos/conf.d/cyclos-httpd.conf
    259 
    260   [cyclos-httpd-wire-gateway-api]
    261   ENABLED = YES
    262 
    263 .. code-block:: ini
    264   :caption: /etc/taler-cyclos/secrets/cyclos-httpd.secret.conf
    265 
    266   [cyclos-httpd-wire-gateway-api]
    267   AUTH_METHOD = bearer
    268   TOKEN = $SECRET_TOKEN
    269 
    270 Check the server is correctly configured:
    271 
    272 .. code-block:: console
    273 
    274   $ sudo -u taler-cyclos-httpd taler-cyclos -c /etc/taler-cyclos/taler-cyclos.conf serve --check
    275 
    276 Configuration
    277 =============
    278 
    279 Here are some configuration options you might want to change:
    280 
    281 Worker frequency
    282 ----------------
    283 
    284 The worker runs periodically to index the history and initiate payments. It also listens to real-time notifications to index new transfers as soon as they are announced.
    285 If the network does not allow notifications to be received, it is best for the worker to run more often; otherwise, you can reduce the frequency. Keep in mind that a very high frequency can place a significant load on your network provider.
    286 
    287 .. code-block:: ini
    288   :caption: /etc/taler-cyclos/conf.d/cyclos-worker.conf
    289 
    290   [cyclos-worker]
    291   FREQUENCY = 3m
    292 
    293 Deployment
    294 ==========
    295 
    296 This chapter describes how to deploy the adapter once the basic installation
    297 and configuration are completed.
    298 
    299 Reverse Proxy Setup
    300 -------------------
    301 
    302 By default, the ``taler-cyclos-httpd`` service listens for HTTP connections
    303 on a UNIX domain socket.  To make the service publicly available, a reverse
    304 proxy such as nginx should be used.  We strongly recommend to configure nginx
    305 to use TLS.
    306 
    307 The ``taler-cyclos`` package ships with a sample configuration that can be
    308 enabled in nginx:
    309 
    310 .. code-block:: shell-session
    311 
    312   # vim /etc/nginx/sites-available/taler-cyclos
    313   < ... customize configuration ... >
    314   # ln -s /etc/nginx/sites-available/taler-cyclos /etc/nginx/sites-enabled/taler-cyclos
    315   # systemctl reload nginx
    316 
    317 With this last step, we are finally ready to launch the
    318 main adapter process.
    319 
    320 Launching the adapter
    321 ---------------------
    322 
    323 .. code-block:: console
    324 
    325   # systemctl enable --now taler-cyclos.target