.. This file is part of GNU TALER. Copyright (C) 2014-2026 Taler Systems SA TALER is free software; you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation; either version 2.1, or (at your option) any later version. TALER is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. You should have received a copy of the GNU Affero General Public License along with TALER; see the file COPYING. If not, see @author Bohdan Potuzhnyi @author Volodymyr Potuzhnyi .. _libeufinconnector_dolibarr_install_config: Install and Configure ===================== .. contents:: :depth: 1 :local: Before you install the LibEuFin Connector module, make sure you already have EBICS data from your bank and a working libeufin-nexus setup on your Dolibarr system. For the libeufin-nexus side, please follow the `GNU Taler Nexus manual `_. Prerequisites ------------- In simple terms, you need: 1. Dolibarr v22+ 2. EBICS access/data from your bank In most cases, this is enough. More specifically, you also need to install libeufin-nexus. For this, you need root access, or you need to know how to install libeufin from source. Happily, this module also shows some instructions that might help your sysadmins make the installation easier and faster. Of course, for full usage of the module, you probably want to activate the next Dolibarr modules: - Sales orders - Vendors - Invoices - Bank & Cash - Scheduled jobs Installation of LibEuFin-Nexus and PostgreSQL --------------------------------------------- Please, please, please follow the Taler docs for the libeufin installation steps: `GNU Taler Nexus manual `_. The only special thing you have to do is create the role that runs Dolibarr and give this role access to ``postgres:///libeufin-nexus``. For this part, the module might show you the next commands, which you might need to share with your admin: PostgreSQL setup: .. code-block:: bash apt-get install postgresql postgresql-client systemctl enable --now postgresql Create PostgreSQL role. This is generated when the Nexus DB role is missing: .. code-block:: bash runuser -u postgres -- psql -tc 'SELECT 1 FROM pg_roles WHERE rolname = '\'''\''' | grep -q 1 || runuser -u postgres -- createuser --no-superuser --no-createdb --no-createrole '' Create PostgreSQL database. This is generated when the Nexus DB database is missing: .. code-block:: bash runuser -u postgres -- psql -tc 'SELECT 1 FROM pg_database WHERE datname = '\'''\''' | grep -q 1 || runuser -u postgres -- createdb --owner='' '' PostgreSQL probe, shown in diagnostics: .. code-block:: bash psql '' -v ON_ERROR_STOP=1 -tAc "SELECT 1;" As soon as you are done with this part, we can actually review the installation of the connector module in Dolibarr. Installation of LibEuFin Connector ---------------------------------- The installation is quite easy. You have to take the module ``.zip`` from the `GitHub releases `_. The module should also be available on `DoliStore `_ later, so you can use that package as well. After you have acquired the module, you need to go to Dolibarr. Below, you can check how to do it. Just tap on the buttons in the same order. This is no different from other custom modules for Dolibarr. .. figure:: ../../images/libeufinconnector-dolibarr/install1.png :alt: Dolibarr setup page for installing an external module :width: 720px :align: center Dolibarr setup page for installing an external module. Follow the link in the banner that appears. Check the next picture for the location. .. figure:: ../../images/libeufinconnector-dolibarr/install2.png :alt: Dolibarr banner after the LibEuFin Connector module is deployed :width: 720px :align: center Dolibarr banner shown after the module is deployed. Of course you have to activate the module. Make sure the region shown with label 1 has a green toggle, then press the settings/gear icon. As such, you have successfully installed the module, and we continue with configuring it. .. figure:: ../../images/libeufinconnector-dolibarr/install3.png :alt: LibEuFin Connector activation and settings button in Dolibarr :width: 720px :align: center LibEuFin Connector activation and settings button in Dolibarr. Configuration of LibEuFin Connector ----------------------------------- If you have not installed libeufin-nexus on the machine with Dolibarr, the module will detect it and show a lovely yellow banner reminding you that you need to install it. .. figure:: ../../images/libeufinconnector-dolibarr/configure1.png :alt: Configuration page warning that libeufin-nexus is missing :width: 720px :align: center Configuration page warning that libeufin-nexus is missing. As soon as you sort out this small issue, you can reload the setup page. The module will detect the module path and show it here, as in the next picture. Next, it is advised to set **Use module-owned local config** to true, labeled with 1. Otherwise, make sure the user that runs Dolibarr has access to the ``Nexus config path`` file. Labels 2 and 3 are pretty much just choices with which you can filter whether you are going to see incoming and outgoing transactions in the module. Label **Demo** means really demo. It activates a special screen, :ref:`libeufinconnector_dolibarr_demo`, which gives mainly 2 things: 1. Create fake incoming transactions 2. See what the actual libeufin-nexus has in memory After you have tested that the module works, and you plan to work only in productive environments, TURN IT OFF. It must become grey. There is additional protection in the fact that a non-admin user has to be granted permission to see it. Yet faking incoming payments is no good for productive systems. .. figure:: ../../images/libeufinconnector-dolibarr/configure2.png :alt: Main LibEuFin Connector settings :width: 720px :align: center Main LibEuFin Connector settings. .. figure:: ../../images/libeufinconnector-dolibarr/configure_special_screen.png :alt: LibEuFin Connector demo screen :width: 720px :align: center LibEuFin Connector demo screen. As we have checked all things from the first part, we can scroll down. Here, the main thing you have to set is the bank account for which you would like to activate libeufin. Ideally, you select the bank account from the selector, and then all the data will be automatically filled from data you previously entered in Dolibarr. For a sample, check the next picture. After you have entered all bank details, you can simply press the save button, labeled 2, and you are done with the module configuration, but not with the configuration of the general system. .. figure:: ../../images/libeufinconnector-dolibarr/configure3.png :alt: LibEuFin Connector bank account configuration :width: 720px :align: center LibEuFin Connector bank account configuration. As you can see by the banner that appeared in the next picture, this is not all the settings that have to be done. More specifically, now we have to do the configuration file of libeufin-nexus. For this, press the **Nexus config** button, labeled with 1. .. figure:: ../../images/libeufinconnector-dolibarr/configure4.png :alt: Configuration warning and Nexus config button :width: 720px :align: center Configuration warning and Nexus config button. After you go to the ``Nexus config`` page, you will probably see some yellow boxes, as in the next picture, indicating problems with the config. To fix them, simply scroll down and fill the empty fields with data you received from your bank. .. figure:: ../../images/libeufinconnector-dolibarr/configure5.png :alt: Nexus config page with missing configuration warnings :width: 720px :align: center Nexus config page with missing configuration warnings. An example of how the filled data might look is shown in the next picture. Scroll down and press **write managed keys to config**. .. note:: If you see ``Failed to write the managed Nexus configuration keys (directory_not_writable)``, go back to the settings part and switch **Use module-owned local config** to green/true. .. figure:: ../../images/libeufinconnector-dolibarr/configure6.png :alt: Filled Nexus configuration form :width: 720px :align: center Filled Nexus configuration form. The config will be verified, and if everything is good, the area in label 1 has no yellow blocks. You will see a screen like the next one. .. figure:: ../../images/libeufinconnector-dolibarr/configure7.png :alt: Nexus configuration successfully verified :width: 720px :align: center Nexus configuration successfully verified. Now that you have a correct config, only one last small step is separating you from using the module: actually starting libeufin-nexus. For this, navigate to ``Nexus operations``, labeled 2 in the previous picture. Starting libeufin-nexus ----------------------- This one is a bit tricky, yet the protocol is quite simple. You do the next: 1. Initialize the Nexus database. 2. Make sure the bank has no keys saved. 3. Run ``Ebics setup``. It will generate and send keys to the bank and fail, of course only in case the EBICS data is correct. 4. Activate the account at the bank. 5. Run ``Ebics setup`` again. It will fail, but if you did everything correctly before, a new button for accepting keys will show up. 6. By accepting keys, the setup will be completed. In a bit more illustrated manner: Before doing any further steps, make sure that the bank does not have any of your saved keys from a previous time. If it does, make sure to ask your bank to clean them before proceeding any further. If you have not installed PostgreSQL, or did not create a database, or did not create a user, the module will tell you this through a yellow note, label 1 in the next picture. By clicking on label 2, logs will be presented, as well as possible solution steps. If you do not see yellow boxes, you can simply proceed by pressing the button labeled 3. This starts the process of the module preparing the libeufin-nexus database. After a couple of seconds, 10-20 seconds, you can update the screen. If everything is good, you will see the run status as ``Success``. After this, you can press the button labeled 4. As previously, you can update the page after 10-20 seconds. .. figure:: ../../images/libeufinconnector-dolibarr/configure8.png :alt: Nexus operations page before EBICS setup :width: 720px :align: center Nexus operations page before EBICS setup. If you did everything correctly before, the thing you are going to see is that ``EBICS setup`` failed. You can investigate the error further by pressing on the region labeled with 1. After this, logs will be dropped down. What you want to see is text like the one shown by label 2, which pretty much means that you simply have to go to your bank and finish the account activation. .. figure:: ../../images/libeufinconnector-dolibarr/configure9.png :alt: EBICS setup failure after sending keys to the bank :width: 720px :align: center EBICS setup failure after sending keys to the bank. After you get confirmation from the bank that your account was activated, you can return to the module page and press **Run EBICS setup** one more time. Update the page after 10-20 seconds, and you will see the next page. .. figure:: ../../images/libeufinconnector-dolibarr/configure10.png :alt: EBICS setup page with bank keys ready to accept :width: 720px :align: center EBICS setup page with bank keys ready to accept. You can now compare keys with the ones shown by your bank and press **Accept bank keys**. Update the page in 10-20 seconds. After this, you have configured your Dolibarr to speak with your bank. You might as well run **Fetch incoming transactions** and **Fetch outgoing payments**. All of this has to be successful, like on the next screen. .. figure:: ../../images/libeufinconnector-dolibarr/configure11.png :alt: Successful Nexus operations after EBICS setup :width: 720px :align: center Successful Nexus operations after EBICS setup. Now you can navigate to the home page, shown in the next picture. And as such, one more time, congratulations on running libeufin and LibEuFin Connector on Dolibarr. .. figure:: ../../images/libeufinconnector-dolibarr/configure12.png :alt: LibEuFin Connector home page after successful setup :width: 720px :align: center LibEuFin Connector home page after successful setup. Next step --------- After the module is installed and enabled, continue with :ref:`libeufinconnector_dolibarr_transactions_incoming` and :ref:`libeufinconnector_dolibarr_transactions_outgoing` to see how incoming and outgoing payments work in this module.