Add libeufin-bank documentation draft

4 files changed, 315 insertions, 0 deletions

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 <taler@gnu.org>.
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 <taler@gnu.org>.