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