Code development platform for open source projects from the European Union institutions 🔵 EU Login authentication by SMS has been phased out. To see alternatives please check here

Skip to content

Changes

Page history
update setup domibus guide authored by Oussama MOULANA's avatar Oussama MOULANA
Show whitespace changes
Inline Side-by-side
CrossBorder-Gateway/Domibus/Server-setup-guide.md 0 → 100644
View page @ ab717466
# :construction: Working in progress :construction:
[[_TOC_]]
# Introduction
This document describes the process to deploy and configure a Crossborder Gateway v0.1 for a POC Node. This component will allow each poc node to provision an eDelivery access point in order to exchange messages with the Central Poc Node.
This deployment and configuration guidelines are inspired by the official documentation of eDelivery Domibus. To find more information, please refer to this [web site](https://ec.europa.eu/digital-building-blocks/wikis/display/DIGITAL/Domibus).
During this process you will :
- Set up a Domibus single instance on your server using Docker
- Configure the keystore and trustore to secure messages to the central poc node
- Configure the Pmode file to reference the central poc node
- Enable authentication to access your Domibus through APIs
- Exchange AS4 messages with the eDelivery Domibus Access Point using SoapUI and the Web Service Plugin
## Variables
The instructions described in those guidelines are using variables that needs to be replaced by the appropriate values in your context :
- **{DOMIBUS_SERVER_DIRECTORY}** : This refers to the directory on your server where Domibus will be set up.
- **{DOMIBUS_HOSTNAME}** : Denotes the public IP address of the server where you plan to install Domibus.
- **{DOMIBUS_PORT}** : Represents the internet-accessible port that you will open for Domibus.
- **{DOMIBUS_ACCESS_POINT}** : This is the designated name for your Domibus instance. Opt for a clear and descriptive name, like _france_ap_.
## Requirement
Before executing the above steps, please make sure that you comply with the below prerequisites:
- You have provisioned a linux server running the Docker engine including docker compose. As a reference, the central POC node is running on a server with the following properties :
- 3 vCPUs
- 4 GB of RAM
- 40 GB of storage
- OS : Ubuntu 22.04 Jammy Jellyfish
- Your server is publicly reachable from internet through a public IP
- You have access to the following [materials](https://drive.google.com/drive/folders/1MSr2KryZ6jtsm5IfdZ-UP3MX0V5Pe-e9?usp=share_link) (Pmode file template, europe_ap certificate)
# How to setup
## 1 - Docker Compose
Access your server using SSH and create the **`{DOMIBUS_SERVER_DIRECTORY}`**. Inside this directory, create a `compose.yaml` file with the following content:
```yaml
#
# Docker compose project used to startup the test environment.
#
# Usage:
# Start: docker-compose up -d
# Shutdown: docker-compose down
# Logs: docker-compose logs
#
# Configuration:
# This file represents the architecture of the Domibus single node setup with MySQL
version: '3.2'
services:
#
# Domibus Tomcat MySQL Configuration
#
# Optional: can provide your own external database
mysql:
image: code.europa.eu:4567/edelivery/docker/domibus-mysql8:5.1.1
environment:
- MYSQL_ROOT_PASSWORD=123456
- MYSQL_DATABASE=domibus
- MYSQL_USER=edelivery
- MYSQL_PASSWORD=edelivery
security_opt:
- seccomp:unconfined
volumes:
- shared_db_file_system:/var/lib/mysql
ports:
- "13306:3306"
tomcati1:
image: code.europa.eu:4567/edelivery/docker/domibus-tomcat9:5.1.1
environment:
- DB_TYPE=MySQL
- DB_HOST=mysql
- DB_PORT=3306
- DB_USER=edelivery
- DB_PASS=edelivery
- LOGGER_LEVEL_ORG_APACHE_CXF=INFO
- CHECK_DEFAULT_PASSWD=false
- domibus.metrics.sl4j.reporter.enable=false
- domibus.metrics.monitor.jms.queues=false
- domibus.metrics.monitor.memory=false
- domibus.metrics.monitor.gc=false
- domibus.metrics.monitor.cached.threads=false
ports:
- "18080:8080"
volumes:
- ./domibus:/data/tomcat/conf/domibus
depends_on:
- mysql
volumes:
shared_db_file_system:
```
If necessary, change the **18080** port to the port you have opened to the internet. This port will be referred to as **`{DOMIBUS_PORT}`**.
> **Note**: If using a reverse proxy, configure it to forward to the internal port.
Execute the following commands at the same level as your `compose.yaml`:
```shell
docker compose up -d
```
The startup process may take 2-5 minutes. Once completed, you can verify that your Domibus server is running by accessing it through the following URL:
```url
http://{DOMIBUS_HOSTNAME}:{DOMIBUS_PORT}/domibus
```
![console](/img/domibus/image1.png)
Stop your Domibus instance using the following command at the same level as your `compose.yaml`:
```shell
docker compose down
```
## Step 2 - Keystore and Trustore configuration
You should now have two JAVA keystores located in **`{DOMIBUS_DOCKER_DIRECTORY}/domibus/keystores`** :
- The `gateway_keystore.jks` will be used to store your own private and public keys.
- The `gateway_truststore.jks` will be used to store the public keys of the other eDelivery access points you want to exchange messages with.
Inside the **{DOMIBUS_DOCKER_DIRECTORY}/domibus/keystores**
Remove `gateway_keystore.jks` and `gateway_trustore.jks` by running this command:
```shell
rm gateway_keystore.jks gateway_truststore.jks
```
Generate a keystore with this command line:
```shell
keytool -keystore gateway_keystore.jks -genkey -alias {DOMIBUS_ACCESS_POINT} -keyalg RSA -keysize 2048 -validity 1461 -storetype JKS
```
After executing this command, you will be prompted to enter information for the keystore.
> **NOTE:** You will need to fill several properties in the interactive prompt. The default password is “test123”, if you change it you have to change it in the domibus.properties as well. This step is described in the next step.
Exports your certificate from a keystore :
```shell
keytool -export -alias {DOMIBUS_ACCESS_POINT} -keystore gateway_keystore.jks -rfc -file {DOMIBUS_ACCESS_POINT}.cert
```
Import your certificat to your trustore:
```shell
keytool -import -alias {DOMIBUS_ACCESS_POINT} -file {DOMIBUS_ACCESS_POINT}.cert -storetype JKS -keystore gateway_truststore.jks
```
## Step 3 - Domibus properties configuration
In the file **{DOMIBUS_DOCKER_DIRECTORY}/domibus/domibus.properties**, find the section:
`Keystore/Truststore (Single Tenancy)`
And assign a password for the keystore you configured earlier
```
#The password used to load the keystore
domibus.security.keystore.password=test123
....
#The private key password
domibus.security.key.private.password=test123
...
#The password used to load the trustStore
domibus.security.truststore.password=test123
```
Set the alias your configured earlier
```
#The alias from the keystore of the private key
domibus.security.key.private.alias={DOMIBUS_ACCESS_POINT}
```
In the `Security` section of the file, activate the security of the following propertie:
```
#To activate security set this to false
#domibus.auth.unsecureLoginAllowed=false
```
## Step 4 - Domibus server configuration
Inside your **{DOMIBUS_SERVER_DIRECTORY}**
Start again the server by doing the command:
```shell
docker compose up -d
```
From your browser, access to your domibus server with the following URL:
```url
http://{DOMIBUS_HOSTNAME}:{DOMIBUS_PORT}/domibus
```
Login in the Domibus Admin Console with the default credentials:
- login : admin
- password : 123456
You can change this password on the top right of the console.
On the left section
Download a copy of the PMode template file [pmode_default.xml](uploads/domibus/PMode-Default-2023-05-02_104857.xml) and replace the following variables with the correct values and upload the file.
<details>
<summary>pmode.xml</summary>
<code>
<?xml version="1.0" encoding="UTF-8"?>
<db:configuration xmlns:db="http://domibus.eu/configuration" party="{DOMIBUS_ACCESS_POINT}">
<mpcs>
<mpc name="defaultMpc"
qualifiedName="http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/defaultMPC"
enabled="true"
default="true"
retention_downloaded="0"
retention_undownloaded="14400"
retention_sent="14400"
delete_message_metadata="false"
max_batch_delete="1000" />
</mpcs>
<businessProcesses>
<roles>
<role name="defaultInitiatorRole"
value="http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/initiator" />
<role name="defaultResponderRole"
value="http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/responder" />
</roles>
<parties>
<partyIdTypes>
<partyIdType name="partyTypeUrn"
value="urn:oasis:names:tc:ebcore:partyid-type:unregistered" />
</partyIdTypes>
<party name="{DOMIBUS_ACCESS_POINT}"
endpoint="http://{DOMIBUS_HOSTNAME}:{DOMIBUS_PORT}/domibus/services/msh">
<identifier partyId="{DOMIBUS_ACCESS_POINT}" partyIdType="partyTypeUrn" />
</party>
<party name="europe_ap"
endpoint="http://51.159.133.186:8080/domibus/services/msh">
<identifier partyId="europe_ap" partyIdType="partyTypeUrn" />
</party>
</parties>
<meps>
<mep name="oneway"
value="http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/oneWay" />
<mep name="twoway"
value="http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/twoWay" />
<binding name="push"
value="http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/push" />
<binding name="pull"
value="http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/pull" />
<binding name="pushAndPush"
value="http:// docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/ pushAndPush" />
</meps>
<properties>
<property name="originalSenderProperty"
key="originalSender"
datatype="string"
required="true" />
<property name="finalRecipientProperty"
key="finalRecipient"
datatype="string"
required="true" />
<propertySet name="eDeliveryPropertySet">
<propertyRef property="finalRecipientProperty" />
<propertyRef property="originalSenderProperty" />
</propertySet>
</properties>
<payloadProfiles>
<payload name="businessContentPayload"
cid="cid:message"
required="true"
mimeType="text/xml" />
<payload name="businessContentAttachment"
cid="cid:attachment"
required="false"
mimeType="application/octet-stream" />
<payloadProfile name="MessageProfile" maxSize="2147483647">
<attachment name="businessContentPayload" />
<attachment name="businessContentAttachment" />
</payloadProfile>
</payloadProfiles>
<securities>
<security name="eDeliveryAS4Policy"
policy="eDeliveryAS4Policy.xml"
signatureMethod="RSA_SHA256" />
</securities>
<errorHandlings>
<errorHandling name="demoErrorHandling"
errorAsResponse="true"
businessErrorNotifyProducer="true"
businessErrorNotifyConsumer="true"
deliveryFailureNotifyProducer="true" />
</errorHandlings>
<agreements>
<agreement name="agreement1" value="A1" type="T1" />
</agreements>
<services>
<service name="testService1" value="bdx:noprocess" type="tc1" />
<service name="testService"
value="http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/service" />
</services>
<actions>
<action name="tc1Action" value="TC1Leg1" />
<action name="testAction"
value="http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/test" />
</actions>
<as4>
<receptionAwareness name="receptionAwareness" retry="12;4;CONSTANT"
duplicateDetection="true" />
<reliability name="AS4Reliability" nonRepudiation="true" replyPattern="response" />
</as4>
<legConfigurations>
<legConfiguration name="pushTestcase1tc1Action"
service="testService1"
action="tc1Action"
defaultMpc="defaultMpc"
reliability="AS4Reliability"
security="eDeliveryAS4Policy"
receptionAwareness="receptionAwareness"
propertySet="eDeliveryPropertySet"
payloadProfile="MessageProfile"
errorHandling="demoErrorHandling"
compressPayloads="true" />
<legConfiguration name="testServiceCase"
service="testService"
action="testAction"
defaultMpc="defaultMpc"
reliability="AS4Reliability"
security="eDeliveryAS4Policy"
receptionAwareness="receptionAwareness"
propertySet="eDeliveryPropertySet"
payloadProfile="MessageProfile"
errorHandling="demoErrorHandling"
compressPayloads="true" />
</legConfigurations>
<process name="tc1Process"
mep="oneway"
binding="push"
initiatorRole="defaultInitiatorRole"
responderRole="defaultResponderRole">
<initiatorParties>
<initiatorParty name="{DOMIBUS_ACCESS_POINT}" />
<initiatorParty name="europe_ap" />
</initiatorParties>
<responderParties>
<responderParty name="{DOMIBUS_ACCESS_POINT}" />
<responderParty name="europe_ap" />
</responderParties>
<legs>
<leg name="pushTestcase1tc1Action" />
<leg name="testServiceCase" />
</legs>
</process>
</businessProcesses>
</db:configuration>
</code>
</details>
You can check on the Parties tab if every parties are configured correctly.
Still on the left side, go to`Certificates` -> `Keystore` section and upload your keystore you generated earlier.
Next, navigate to `Certificates` -> `Truststore` and add the certificates for each Access Point you wish to establish an exchange with.
You can find the `europe_ap` certificate here[europe_ap.cert](uploads/domibus/europe_ap.cert)
Reach out the WP5 core team with the following details:
Provide the URL of your Domibus, which should be: **http://{DOMIBUS_HOSTNAME}:{DOMIBUS_PORT}/domibus**
Attach the certificate you generated earlier in your keystores folder, named {DOMIBUS_ACCESS_POINT}.cert.
In the menu bar, navigate to `Plugin User`. Create a new plugin user by clicking on “New”
Make sure that you save your modification.
# Test your connection
Navigate into `Connection Monitoring` and try to send a message, if the status is green your domibus is ready to exchange messages.
\ No newline at end of file

For further information about the platform and support, please see https://code.europa.eu/info/about