diff options
Diffstat (limited to 'libeufin/nexus-tutorial.rst')
| -rw-r--r-- | libeufin/nexus-tutorial.rst | 115 |
1 files changed, 68 insertions, 47 deletions
diff --git a/libeufin/nexus-tutorial.rst b/libeufin/nexus-tutorial.rst index 6ef78829..c00b9d4e 100644 --- a/libeufin/nexus-tutorial.rst +++ b/libeufin/nexus-tutorial.rst @@ -19,6 +19,28 @@ steps in "Setting up the Sandbox". Installing LibEuFin =================== +.. warning:: + + LibEuFin does not yet ship with any systemd unit files. + + There is an `open bug report <https://bugs.gnunet.org/view.php?id=6719>`__ + for this issue. + + +Installation on Debian +---------------------- + +.. include:: ../frags/installing-debian.rst + +To install LibEuFin, you can now simply run: + +.. code-block:: console + + # apt install libeufin + +Run-time dependencies +--------------------- + LibEuFin has the following run-time dependencies: * OpenJDK 11 @@ -26,6 +48,9 @@ LibEuFin has the following run-time dependencies: * python3-click (can be installed via ``pip3 install click``) * python3-requests (can be installed via ``pip3 install requests``) +These dependencies only need to be installed manually when building from source +or using the prebuilt binaries. + Downloading prebuilt binaries ----------------------------- @@ -165,10 +190,21 @@ Use the following command to run the nexus service: $ libeufin-nexus serve --port 5001 By default, the SQLite3 database ``/tmp/libeufin-nexus.sqlite3`` will be used. +The database can be specified as a JDBC connection URI with the +``--db-conn-string=$DBCONN`` option. Only *SQLite* and *PostgreSQL (only via +TCP)* are supported right now. + +.. warning:: + + For production-grade deployments of LibEuFin, we do not recommend specifying the + secret database credentials via command line arguments, as can will expose + those credentials to other users. + + Instead, the DB connection string should be specified in an environment variable + (which can be set in the systemd unit via an ``EnvironmentFile`` option) + once LibEuFin supports this (see the corresponding + `bug tracker entry <https://bugs.gnunet.org/view.php?id=6720>`__). -We recommend using the ``--db-conn-string=$DBCONN`` option. It instructs Nexus -to reach the database addressed by the JDBC connection URI. Only *SQLite* and -*PostgreSQL (only via TCP)* are supported right now. For example: @@ -187,7 +223,8 @@ to create less privileged users is offered. .. note:: - Privilege separation is not fully implemented yet. + User and permissions management in LibEuFin is still under development. + In particular, permissions for non-superusers are very limited at the moment. The command line interface needs the following three values to be defined in the environment: ``LIBEUFIN_NEXUS_URL``, ``LIBEUFIN_NEXUS_USERNAME``, @@ -280,10 +317,10 @@ step is needed to let the user pick a custom name for such accounts. connections \ import-bank-account \ --offered-account-id testacct01 \ - --nexus-bank-account-id $CUSTOM_RENAMING_FOR_ACCOUNT \ + --nexus-bank-account-id $LOCAL_ACCOUNT_NAME \ $CONNECTION_NAME -Once a Nexus user imported a bank account (``$CUSTOM_RENAMING_FOR_ACCOUNT``) +Once a Nexus user imported a bank account (``$LOCAL_ACCOUNT_NAME``) under a certain connection (``$CONNECTION_NAME``), it is possible to accomplish the usual operations for any bank account: asking for the list of transactions, and making a payment. @@ -291,22 +328,16 @@ list of transactions, and making a payment. Request history of transactions =============================== -.. - - FIXME: explain why requesting the history - goes through these two-phases. +The LibEuFin nexus keeps a local copy of the bank account's transaction +history. Before querying transactions locally, it is necessary +to request transactions for the bank account via the bank connection. -It is first needed to tell Nexus to download the latest news -from the bank, and then ask it again to return the results. - -This command asks Nexus to *download the latest bank statements*: +This command asks Nexus to download the latest transaction reports/statements +through the bank connection: .. code-block:: console - $ libeufin-cli \ - accounts \ - fetch-transactions \ - $CUSTOM_RENAMING_FOR_ACCOUNT + $ libeufin-cli accounts fetch-transactions $LOCAL_ACCOUNT_NAME .. note:: @@ -316,36 +347,32 @@ This command asks Nexus to *download the latest bank statements*: reports). Once Nexus stored all the information in the database, the -client can ask to actually **see** the transactions: +client can ask to actually see the transactions: .. code-block:: console - $ libeufin-cli accounts \ - transactions \ - $CUSTOM_RENAMING_FOR_ACCOUNT + $ libeufin-cli accounts transactions $LOCAL_ACCOUNT_NAME Make a payment ============== -.. - - FIXME: explain why payments go through these two-phases. +Payments pass through two phases: preparation and submission. The preparation +phase assigns the payment initiation a unique ID, which prevents accidental +double submissions of payments in case of network failures or other +disruptions. -Payments pass through two phases: preparation and submission. The following command prepares a payment: .. code-block:: console - $ libeufin-cli \ - accounts \ - prepare-payment \ + $ libeufin-cli accounts prepare-payment \ --creditor-iban $IBAN_TO_SEND_MONEY_TO \ --creditor-bic $BIC_TO_SEND_MONEY_TO \ --creditor-name $CREDITOR_NAME \ --payment-amount $AMOUNT \ --payment-subject $SUBJECT \ - $CUSTOM_RENAMING_FOR_ACCOUNT + $LOCAL_ACCOUNT_NAME Note: the ``$AMOUNT`` value needs the format ``X.Y:CURRENCY``; for example ``10:EUR``, or ``1.01:EUR``. @@ -356,11 +383,9 @@ in the next step, to **send the payment instructions to the bank**: .. code-block:: console - $ libeufin-cli \ - accounts \ - submit-payment \ - --payment-uuid $UUID \ - $CUSTOM_RENAMING_FOR_ACCOUNT + $ libeufin-cli accounts submit-payment \ + --payment-uuid $UUID \ + $LOCAL_ACCOUNT_NAME Automatic scheduling ==================== @@ -415,12 +440,10 @@ INI and HIA secret keys will be restored for the requesting user. .. code-block:: console - $ libeufin-cli \ - connection \ - restore-backup \ - --passphrase $SECRET \ - --backup-file $BACKUP_FILE \ - $CONNECTION_NAME + $ libeufin-cli connection \ restore-backup + --passphrase $SECRET \ + --backup-file $BACKUP_FILE \ + $CONNECTION_NAME Creating a Taler facade ======================= @@ -436,12 +459,10 @@ existing bank account / connection pair. .. code-block:: console - $ libeufin-cli \ - facades \ - new-facade \ - --facade-name $FACADE_NAME \ - $CONNECTION_NAME \ - $CUSTOM_RENAMING_FOR_ACCOUNT + $ libeufin-cli facades new-facade \ + --facade-name $FACADE_NAME \ + $CONNECTION_NAME \ + $LOCAL_ACCOUNT_NAME At this point, the additional *taler-wire-gateway* (FIXME: link here to API here) API becomes offered by the Nexus. The purpose |