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