8. Cyclos Adapter Setup Manual#
taler-cyclos is a Cyclos Taler adapter.
This manual targets system administrators who want to install and operate a Cyclos GNU Taler adapter
8.1. Installation#
8.1.1. Installing on Debian#
To install the GNU Taler Debian packages, first ensure that you have the right Debian distribution. At this time, the packages are built for Debian trixie.
You need to add a file to import the GNU Taler packages. Typically,
this is done by adding a file /etc/apt/sources.list.d/taler.list that
looks like this:
deb [signed-by=/etc/apt/keyrings/taler-systems.gpg] https://deb.taler.net/apt/debian trixie main
Next, you must import the Taler Systems SA public package signing key into your keyring and update the package lists:
# wget -O /etc/apt/keyrings/taler-systems.gpg \
https://taler.net/taler-systems.gpg
# apt update
Note
You may want to verify the correctness of the Taler Systems SA key out-of-band.
Now your system is ready to install the official GNU Taler binary packages using apt.
To install the adapter, you can now simply run:
# apt install taler-cyclos
8.1.2. Installing on Ubuntu#
To install the GNU Taler Ubuntu packages, first ensure that you have
the right Ubuntu distribution. At this time, the packages are built for
Ubuntu Lunar and Ubuntu Jammy. Make sure to have universe in your
/etc/apt/sources.list.d/ubuntu.sources (after main)
as we depend on some packages from Ubuntu universe.
A typical /etc/apt/sources.list.d/taler.list file for this setup
would look like this for Ubuntu Noble:
deb [signed-by=/etc/apt/keyrings/taler-systems.gpg] https://deb.taler.net/apt/ubuntu/ noble main
Next, you must import the Taler Systems SA public package signing key into your keyring and update the package lists:
# wget -O /etc/apt/keyrings/taler-systems.gpg \
https://taler.net/taler-systems.gpg
# apt update
Note
You may want to verify the correctness of the Taler Systems key out-of-band.
Now your system is ready to install the official GNU Taler binary packages using apt.
To install the adapter, you can now simply run:
# apt install taler-cyclos
8.1.3. Building from source#
Cyclos Adapter belongs to the Taler Rust project, and can be downloaded via Git:
$ git clone git://git.taler.net/taler-rust
$ cd taler-rust
You will need the latest version of the rust stable toolchain and a C toolchain:
$ sudo apt install rustup build-essential
$ rustup toolchain install stable
Then from top-level run:
$ ./bootstrap
To install the adapter as a Debian/Ubuntu package with an automated secure setup and systemd services:
$ sudo apt install debhelper
$ make deb
$ sudo dpkg -i ../taler-cyclos*.deb
If the previous steps succeeded, the taler-cyclos command should be found in the $PATH.
8.1.4. Services, users, groups and file system hierarchy#
The taler-cyclos package will create several system users to compartmentalize different parts of the system:
taler-cyclos-httpd: runs the HTTP daemon with the API logic.taler-cyclos-worker: runs the worker daemon interacting with the Cyclos API.postgres: runs the PostgreSQL database (from postgresql package).
The adapter setup uses the following system groups:
taler-cyclos-db: group for all adapter users with direct database access, specifically taler-cyclos-httpd and taler-cyclos-worker.
The package will deploy systemd service files in
/usr/lib/systemd/system/ for the various components:
taler-cyclos-httpd.service: adapter REST API.taler-cyclos-httpd.socket: systemd socket activation for the HTTP daemon.taler-cyclos-worker.service: worker deamon interacting with the Cyclos API.taler-cyclos.target: main target for the adapter to be operational.
The deployment creates the following key locations in the system:
/etc/taler-cyclos/: configuration files./run/taler-cyclos/: contains the UNIX domain sockets for inter-process communication (IPC).
8.2. Configuration Fundamentals#
This chapter provides fundamental details about the adapter configuration.
The configuration for all adapter components uses a single configuration file
as entry point: /etc/taler-cyclos/taler-cyclos.conf.
System defaults are automatically loaded from files in
/usr/share/taler-cyclos/config.d.
These default files should never be modified.
The default configuration taler-cyclos.conf configuration file
also includes all configuration files in /etc/taler-cyclos/conf.d.
The settings from files in
conf.d are only relevant to particular components of an adapter, while
taler-cyclos.conf contains settings that affect all adapter components.
The directory /etc/taler-cyclos/secrets contains configuration file snippets with
values that should only be readable to certain users. They are included with the @inline-secret@
directive and should end with .secret.conf.
To view the entire configuration annotated with the source of each configuration option, you
can use the taler-cyclos config helper:
# taler-cyclos config dump --diagnostics
8.3. Basic Setup#
8.3.1. Database setup#
The configuration file must include a connection string that tells the adapter how it should connect to the database. The default is:
[cyclosdb-postgres]
config = postgres:///taler-cyclos
If the database is run on a different host, please follow the instructions from the PostgreSQL manual for configuring remote access.
Assuming the configuration is correct, the following command initializes (or upgrades) the database schema using: You can then use a script to automate a secure database setup:
$ sudo taler-cyclos-dbconfig
8.3.2. Worker setup#
You will need a Cyclos account to sync. Update the configuration files:
[cyclos]
CURRENCY = KUDOS
CYCLOS_URL = https://demo.cyclos.org/
[cyclos-worker]
USERNAME = admin
PASSWORD = password
And then run the setup process:
$ sudo -u taler-cyclos-worker taler-cyclos -c /etc/taler-cyclos/taler-cyclos.conf setup
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.
The setup process should fail and provide you with the information needed to fill in the required Cyclos IDs:
[cyclos]
ACCOUNT_ID = 7762070814178012479
NAME = John Smith S.A.
[cyclos-worker]
ACCOUNT_TYPE_ID = 7762070814178012479
PAYMENT_TYPE_ID = 7762070814178012479
And finaly run the setup process again:
$ sudo -u taler-cyclos-worker taler-cyclos -c /etc/taler-cyclos/taler-cyclos.conf setup
This time, you should not see any errors; if you do, you should modify the configuration until it works.
8.3.3. Wire Gateway setup#
Update the configuration files:
[cyclos-httpd-wire-gateway-api]
ENABLED = YES
[cyclos-httpd-wire-gateway-api]
AUTH_METHOD = bearer
TOKEN = $SECRET_TOKEN
Check the server is correctly configured:
$ sudo -u taler-cyclos-httpd taler-cyclos -c /etc/taler-cyclos/taler-cyclos.conf serve --check
8.4. Configuration#
Here are some configuration you might want to change:
8.4.1. Worker frequency#
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. 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.
[cyclos-worker]
FREQUENCY = 3m
8.5. Deployment#
This chapter describes how to deploy the adapter once the basic installation and configuration are completed.
8.5.1. Reverse Proxy Setup#
By default, the taler-cyclos-httpd service listens for HTTP connections
on a UNIX domain socket. To make the service publicly available, a reverse
proxy such as nginx should be used. We strongly recommend to configure nginx
to use TLS.
The taler-cyclos package ships with a sample configuration that can be
enabled in nginx:
# vim /etc/nginx/sites-available/taler-cyclos
< ... customize configuration ... >
# ln -s /etc/nginx/sites-available/taler-cyclos /etc/nginx/sites-enabled/taler-cyclos
# systemctl reload nginx
With this last step, we are finally ready to launch the main adapter process.
8.5.2. Launching the adapter#
$ sudo systemctl start taler-cyclos.target