nexus manual

1 files changed, 93 insertions, 0 deletions

diff --git a/libeufin/nexus-manual.rst b/libeufin/nexus-manual.rst
new file mode 100644
index 00000000..1c8adf59
--- /dev/null
+++ b/libeufin/nexus-manual.rst
@@ -0,0 +1,93 @@
+.. target audience: operator, developer
+
+LibEuFin Manual
+###############
+
+.. contents:: Table of Contents
+
+LibEuFin Nexus is an EBICS facilitator.  It offers a command line
+interface to setup EBICS access, download banking records, and submit payments.
+Future versions will offer a Web API to allow Taler Exchanges to talk to their
+banks.
+
+In this manual, we explain how to setup an EBICS subscriber.  We assume that
+the bank had already granted EBICS access to the subscriber.  The installation
+is described at `Installing Nexus`_.
+
+Setting up the EBICS subscriber
+===============================
+
+The following snippet shows the mandatory configuration values.
+
+.. code-block:: console
+
+  [nexus-postgres]
+  CONFIG = postgres:///libeufincheck
+
+  [nexus-ebics]
+  CURRENCY = EUR
+  HOST_BASE_URL = http://bank.example.com/
+  HOST_ID = mybank
+  USER_ID = myuser
+  PARTNER_ID = myorg
+  IBAN = myiban
+  BIC = mybic
+  NAME = myname
+  BANK_PUBLIC_KEYS_FILE = enc-auth-keys.json
+  CLIENT_PRIVATE_KEYS_FILE = private-keys-again.json
+  BANK_DIALECT = postfinance
+
+Assuming that the configuration file exists at ``$config_file``, the following
+command would start the EBICS setup process.  The files CLIENT_PRIVATE_KEYS_FILE
+and BANK_PUBLIC_KEYS_FILE would be created at the CWD.  Adjust their path to your
+setup ('$HOME' is currently not supported along paths).
+
+.. code-block:: console
+
+  libeufin-nexus ebics-setup -c $config_file
+
+If the previous command succeeded, the subscriber keys reached the bank, but the setup
+**should** fail with an ``EBICS_AUTHENTICATION_FAILED`` error code.  That happens because
+the client tries to download the bank keys *before* having confirmed the subscriber keys
+via the traditional post service.
+
+To that purpose, the previous run should have left a PDF document that the subscriber can
+print, sign, and send to the bank to confirm their subscriber keys.  Look for the message
+looking like ``PDF file with keys hex encoding created at: /tmp/libeufin-nexus-keys-$timestamp.pdf``.
+
+Once the bank received and approved such printed document, run the same command again, in
+order to download the bank keys and let the user accept them.
+
+.. code-block:: console
+
+  libeufin-nexus ebics-setup -c $config_file
+
+The setup is considered finished once both party have accepted the counterpart keys.
+
+Installing Nexus
+================
+
+The following section was tested on an *OpenJDK 17* environment.
+
+Building from source
+--------------------
+
+Nexus 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-nexus 
+
+If the previous steps succeeded, the ``libeufin-nexus`` command should
+be found in the $PATH.
+