2.4.2. Install and Configure

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.

2.4.2.1. 前提条件

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

2.4.2.2. 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:

apt-get install postgresql postgresql-client
systemctl enable --now postgresql

Create PostgreSQL role. This is generated when the Nexus DB role is missing:

runuser -u postgres -- psql -tc 'SELECT 1 FROM pg_roles WHERE rolname = '\''<role>'\''' | grep -q 1 || runuser -u postgres -- createuser --no-superuser --no-createdb --no-createrole '<role>'

Create PostgreSQL database. This is generated when the Nexus DB database is missing:

runuser -u postgres -- psql -tc 'SELECT 1 FROM pg_database WHERE datname = '\''<database>'\''' | grep -q 1 || runuser -u postgres -- createdb --owner='<role>' '<database>'

PostgreSQL probe, shown in diagnostics:

psql '<postgres-connection-string>' -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.

2.4.2.3. 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.

Dolibarr setup page for installing an external module.

Follow the link in the banner that appears. Check the next picture for the location.

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.

LibEuFin Connector activation and settings button in Dolibarr.

2.4.2.4. 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.

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, 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.

Main LibEuFin Connector settings.

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.

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.

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.

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.

注釈

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.

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.

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.

2.4.2.5. 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.

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.

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.

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.

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.

LibEuFin Connector home page after successful setup.

2.4.2.6. Next step

After the module is installed and enabled, continue with Incoming Transactions and Outgoing Transactions to see how incoming and outgoing payments work in this module.