From f065f89fcf26e27d925d6b81b64828fb083be886 Mon Sep 17 00:00:00 2001 From: Antoine A <> Date: Mon, 27 Nov 2023 15:55:07 +0000 Subject: Add libeufin-bank documentation draft --- libeufin/bank-manual.rst | 116 ++++++++++++++++++++++++++++++++++++++ libeufin/index.rst | 1 + manpages/libeufin-bank.1.rst | 103 +++++++++++++++++++++++++++++++++ manpages/libeufin-bank.conf.5.rst | 95 +++++++++++++++++++++++++++++++ 4 files changed, 315 insertions(+) create mode 100644 libeufin/bank-manual.rst create mode 100644 manpages/libeufin-bank.1.rst create mode 100644 manpages/libeufin-bank.conf.5.rst diff --git a/libeufin/bank-manual.rst b/libeufin/bank-manual.rst new file mode 100644 index 00000000..40e047db --- /dev/null +++ b/libeufin/bank-manual.rst @@ -0,0 +1,116 @@ +.. target audience: operator, developer + +Bank Manual +########### + +.. contents:: Table of Contents + +LibEuFin Bank implements a simple core banking system with +account and REST APIs, including REST APIs for a Web interface +and REST APIs to interact with GNU Taler components. + +In this manual, we explain how to setup a bank. + +Installing Bank +=============== + +The following section was tested on an *OpenJDK 17* environment. + +Building from source +-------------------- + +Bank belongs to the LibEuFin project, and can be downloaded via Git: + +.. code-block:: console + + $ git clone git://git.taler.net/libeufin + +Note that Kotlin and Gradle should already work on the host system. + +Navigate into the *libeufin* local repository, and from top-level run: + +.. code-block:: console + + $ ./bootstrap + $ ./configure --prefix=$PREFIX + $ make install-bank + +If the previous steps succeeded, the ``libeufin-bank`` command should +be found in the $PATH. + +Setting up the LibEuFin Bank +============================ + +The following snippet shows the mandatory configuration values. + +.. code-block:: console + + [libeufin-bank] + CURRENCY = KUDOS + + # Debt limit + DEFAULT_CUSTOMER_DEBT_LIMIT = KUDOS:0 + DEFAULT_ADMIN_DEBT_LIMIT = KUDOS:200000000 + + # Server + SERVE = tcp + PORT = 8080 + + [libeufin-bankdb-postgres] + CONFIG = postgresql:///libeufinbank + +.. note:: + Refer to the manpage ``libeufin-man.conf(5)`` + for the full array of configuration values. + +Assuming that the configuration file exists at ``$config_file``, the following +command would define the database schema and create an admin account. + +.. code-block:: console + + libeufin-bank dbinit -c $config_file + +If you wish to authenticate as admin, you must change the account password. + +.. code-block:: console + + libeufin-bank passwd -c $config_file admin $PASSWORD + +Then you can start the HTTP server. + +.. code-block:: console + + libeufin-bank serve -c $config_file + +Enable regional currency conversion +=================================== + +.. note:: + You need to have LibEuFin Nexus running to enable conversion. + Refers to ``nexus-manual.conf`` for more details. + +First you have to create an exchange account with username ``exchange``. + +TODO + +Then you have to enable conversion in configuration and enable at least one TAN channel for cashout. + +.. code-block:: console + + [libeufin-bank] + ALLOW_CONVERSION = yes + + TAN_SMS = libeufin-tan-sms.sh + # And/Or + TAN_EMAIL = libeufin-tan-email.sh + +Assuming that the configuration file exists at ``$config_file``, the following +command would start the server with conversion API enabled. + +.. code-block:: console + + libeufin-bank serve -c $config_file + +Finally you have to setup conversion rates though the SPA. + +TODO \ No newline at end of file diff --git a/libeufin/index.rst b/libeufin/index.rst index 5e7fdf6d..985e92b6 100644 --- a/libeufin/index.rst +++ b/libeufin/index.rst @@ -8,4 +8,5 @@ LibEuFin is a project providing free software tooling for European FinTech. :glob: nexus-manual + bank-manual setup-ebics-at-postfinance diff --git a/manpages/libeufin-bank.1.rst b/manpages/libeufin-bank.1.rst new file mode 100644 index 00000000..681eb3ab --- /dev/null +++ b/manpages/libeufin-bank.1.rst @@ -0,0 +1,103 @@ +libeufin-bank(1) +################# + +.. only:: html + + Name + ==== + + **libeufin-bank** - LibEuFin Bank + + +Synopsis +======== + +**libeufin-bank** +[**-h** | **--help**] +[**--version**] +COMMAND [ARGS...] + +Subcommands: **serve**, **dbinit**, **passwd**, **config** + + +Description +=========== + +**libeufin-bank** is a program that implements a simple core banking system with +account and REST APIs, including REST APIs for a Web interface +and REST APIs to interact with GNU Taler components. + +Its options are as follows: + +**-h** \| **--help** + Print short help on options. + +**–version** + Print version information. + +The interaction model is as follows: + +- Configure the database with commands ``dbinit``. + +- Set admin account password with commands ``passwd``. + +- Start the HTTP server with command ``serve``. + Let this run in a shell, writing logs to stderr. + +The following sections describe each command in detail. + +dbinit +------ + +This command defines the database schema for LibEuFin Bank. It is mandatory to run this command before invoking the ``serve`` command. + +Its options are as follows: + +**-h** \| **--help** + Print short help on options. +**-c** \| **--config** \ ‌\ *FILENAME* + Specifies the configuration file. +**-r** \| **--reset** + If present, deletes any database table (WARNING: potential data loss) + + +serve +----- + +This command starts the HTTP server. + +Its options are as follows: + +**-h** \| **--help** + Print short help on options. +**-c** \| **--config** \ ‌\ *FILENAME* + Specifies the configuration file. + +passwd +------ + +This command change any account password. + +It takes two arguments, the account login and the account new password. + +Its options are as follows: + +**-h** \| **--help** + Print short help on options. +**-c** \| **--config** \ ‌\ *FILENAME* + Specifies the configuration file. + +config +------ + +TODO + +SEE ALSO +======== + +libeufin-bank.conf(5) + +Bugs +==== + +Report bugs by using https://bugs.taler.net or by sending electronic mail to . diff --git a/manpages/libeufin-bank.conf.5.rst b/manpages/libeufin-bank.conf.5.rst new file mode 100644 index 00000000..b52f7a92 --- /dev/null +++ b/manpages/libeufin-bank.conf.5.rst @@ -0,0 +1,95 @@ +libeufin-bank.conf(5) +###################### + +.. only:: html + + Name + ==== + + **libeufin-bank.conf** - LibEuFin Bank configuration file + + +Description +=========== + +.. include:: ../frags/common-conf-syntax.rst + +Files containing default values for many of the options described below +are installed under ``$TALER_PREFIX/share/libeufin-bank/config.d/``. +The configuration file given with **-c** to Taler binaries +overrides these defaults. + +A configuration file may include another, by using the ``@INLINE@`` directive, +for example, in ``main.conf``, you could write ``@INLINE@ sub.conf`` to +include the entirety of ``sub.conf`` at that point in ``main.conf``. + +Be extra careful when using ``taler-config -V VALUE`` to change configuration +values: it will destroy all uses of ``@INLINE@`` and furthermore remove all +comments from the configuration file! + +GLOBAL OPTIONS +-------------- + +The following options are from the “[libeufin-bank]” section. + +CURRENCY + Internal currency of the libeufin-bank, e.g. “EUR” for Euro. + +DEFAULT_CUSTOMER_DEBT_LIMIT + Default debt limit for newly created customer accounts. + +DEFAULT_ADMIN_DEBT_LIMIT + Default debt limit of the admin. Typically higher, since sign-up bonuses and cashin are deducted from the admin account. + +REGISTRATION_BONUS + Value of the registration bonus for new users. Defaults to CURRENCY:0 if not specified. + +ALLOW_REGISTRATION + Whether anyone can create a new account or whether this action is reserved for the admin. Defaults to no if not specified. + +ALLOW_ACCOUNT_DELETION + Whether anyone can delete its account or whether this action is reserved for the admin. Defaults to no if not specified. + +ALLOW_CONVERSION + Whether regional currency conversion is enabled. Defaults to no if not specified. + +TAN_SMS + Path to TAN challenge transmission script via sms. If not specified, this TAN channel wil be unuspported. + +TAN_EMAIL + Path to TAN challenge transmission script via email. If not specified, this TAN channel wil be unuspported. + +SERVE + This can either be ``tcp`` or ``unix``. + +PORT + Port on which the HTTP server listens, e.g. 9967. + Only used if ``SERVE`` is ``tcp``. + +UNIXPATH + Which unix domain path should we bind to? + Only used if ``SERVE`` is ``unix``. + +UNIXPATH_MODE = 660 + What should be the file access permissions for ``UNIXPATH``? + Only used if ``SERVE`` is ``unix``. + +DATABASE OPTIONS +---------------- + +Setting the database belongs to the “[libeufin-bankdb-postgres]” section and the +following value. + +CONFIG + PostgreSQL connection string. + +SEE ALSO +======== + +libeufin-bank(1). + +BUGS +==== + +Report bugs by using https://bugs.taler.net/ or by sending electronic +mail to . -- cgit v1.2.3