CrossBorder-Gateway/Domibus/Server-setup-guide.md

@@ -16,18 +16,19 @@ Throughout this process, you will:
 ## Variables
 The instructions in these guidelines use variables that must be replaced with the appropriate values in your context:
 
+- **`{ADMIN_USER}`**: Represents the admin user of the Linux terminal on the server.
 - **`{DOMIBUS_SERVER_DIRECTORY}`**: This signifies the directory on your server where Domibus will be installed.
 - **`{DOMIBUS_HOSTNAME}`**: Denotes the public IP address of the server where you intend 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. Choose a clear and descriptive name, such as `france_ap`.
 - **`{KEYSTORE_PASSWORD}`**: Refers to the password for your Java KeyStore.
 - **`{PRIVATE_KEY_PASSWORD}`**: Refers to the password for the private key within your Java KeyStore.
-- **`{TRUSTORE_PASSWORD}`**: Refers to the password for your Java TrustStore.
+- **`{TRUSTSTORE_PASSWORD}`**: Refers to the password for your Java TrustStore.
 
 ## Requirement:
-Before proceeding with the above steps, ensure that your environment meets the following prerequisites:
+Before proceeding with the above steps, ensure that your server environment meets the following prerequisites:
 
-Provision a Linux server with the Docker engine, including Docker Compose. As a reference, the EU Domibus server is running with the following specifications:
+Provision a Linux server. As a reference, the EU Domibus server is running with the following specifications:
 - 3 CPUs
 - 4 GB of RAM
 - 40 GB of storage
@@ -35,16 +36,61 @@ Provision a Linux server with the Docker engine, including Docker Compose. As a
 Ensure your server is publicly accessible from the internet through a public IP. The instructions are demonstrated on an `Ubuntu 22.04 Jammy Jellyfish` server, but other Linux distributions are also compatible.
 
 To begin the setup, ensure you have the following:
-- The capability to generate a `Java KeyStore`
-- Access to the files within the [eu-Domibus](https://drive.google.com/drive/folders/1rj7ezhFDjrxZS_CZG6ZKApU57-htG0zA?usp=drive_link) folder.
+- [Docker](https://docs.docker.com/engine/install/ubuntu/) installed 
+- The capability to generate a `Java KeyStore`, you have the option to install the headless version of `OpenJDK-17`, like `OpenJDK-17-jre-headless`.
+- Authorization access from Google Drive to the files within the [eu-Domibus](https://drive.google.com/drive/folders/1rj7ezhFDjrxZS_CZG6ZKApU57-htG0zA?usp=drive_link) folder.
+
+>**Note**: Most steps are carried out on the server, while some require action from your personal computer. Look for the following emojis at the beginning of each set of steps to determine where each action should be performed:
+>- :globe_with_meridians: indicates steps to be executed on the server.
+>- 💻 indicates steps to be performed on your personal computer.
 
 ## Sources
 - [Domibus official documentation](https://ec.europa.eu/digital-building-blocks/wikis/display/DIGITAL/Domibus)
 - [eDelivery repository](https://code.europa.eu/edelivery)
 
 # How to setup
+### A - Admin User
+:globe_with_meridians:
+As a best practice, create a dedicated user with appropriate privileges as the first step for enhanced security and adherence to the principle of least privilege.
+
+- Create an admin username of your choice.
+```shell
+sudo adduser {ADMIN_USER}
+```
+
+- Add the new user to the sudo group
+```shell
+sudo usermod -aG sudo {ADMIN_USER}
+```
+- Disable root login via SSH by setting `PermitRootLogin` to `no`
+```shell
+sudo nano /etc/ssh/sshd_config
+```
+- Restart SSH
+```shell
+sudo systemctl restart ssh
+```
+### B - Docker group
+:globe_with_meridians:
+For better security, run Docker as a regular user. By default, Docker requires root privileges `sudo`. Follow these steps:
+
+- Create a `docker` group if it doesn't exist.
+```shell
+sudo groupadd docker
+```
+- Add the current user in the group `docker``
+```shell
+sudo usermod -aG docker {ADMIN_USER}
+```
+- Activate the new group membership in the current shell session. By default, the new group is applied in the next login.
+```shell
+newgrp docker
+```
+
 ## 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:
+:globe_with_meridians:
+Access your server using SSH.
+Consider creating the **`{DOMIBUS_SERVER_DIRECTORY}`** in the **`/opt/`** folder. Within this directory, establish a `compose.yaml` file containing the following content:
 
 ```yaml
 #
@@ -107,14 +153,14 @@ volumes:
 
 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 within the directory identified as **`{DOMIBUS_SERVER_DIRECTORY}`**
 ```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:
+The startup process may take 2-5 minutes. Once completed, you can verify that your Domibus server is running by accessing on your personal computer by opening a navigator through the following URL:
+
+:computer:
 ```http
 http://{DOMIBUS_HOSTNAME}:{DOMIBUS_PORT}/domibus
 ```
@@ -122,10 +168,11 @@ http://{DOMIBUS_HOSTNAME}:{DOMIBUS_PORT}/domibus
 
 
 ## 2 - Self-Signed Certificate
+:globe_with_meridians:
 > :warning: **Attention**:
 Self-signed certificates are intended for testing purposes only and should not be used in production. For production use, consider obtaining certificates from a trusted certificate provider. Additional information on certificate providers can be found [here](https://ec.europa.eu/digital-building-blocks/wikis/display/DIGITAL/PKI+Service).
 
-Make sure you have the Java KeyStore/TrustStore located in  **`{DOMIBUS_DOCKER_DIRECTORY}/domibus/keystores`** : 
+Make sure you have the Java KeyStore/TrustStore located in  **`{DOMIBUS_SERVER_DIRECTORY}/domibus/keystores`** : 
 - `gateway_keystore.jks` store your private and public keys.
 - `gateway_truststore.jks` store the public keys of other eDelivery Access Points for message exchange.
 
@@ -152,14 +199,28 @@ Import your certificate into your TrustStore:
 keytool -import -file {DOMIBUS_ACCESS_POINT}.cer -alias {DOMIBUS_ACCESS_POINT} -keystore gateway_truststore.jks -storetype JKS -storepass {TRUSTSTORE_PASSWORD}
 ```
 
-Contact the WP5 core team and provide them with the following information:
+###:construction: under construction :construction:
+Contact the Central Service team and provide them with the following information:
 ```
 {DOMIBUS_HOSTNAME}:{DOMIBUS_PORT}
 ```
-Attach the certificate file, `{DOMIBUS_ACCESS_POINT}.cer`, generated in your **`keystores`** folder. This step is crucial for the WP5 core team to include your public key in the list of authorized parties on the EU Access Point.
+Attach the certificate file, `{DOMIBUS_ACCESS_POINT}.cer`, generated in your **`{DOMIBUS_SERVER_DIRECTORY}/domibus/keystores`** folder. This step is crucial for the Central Service team to include your public key in the list of authorized parties on the Central Access Point.
+
+You may need to use `scp` on your PC to copy this file from the server to your personal computer. For example:
+
+:computer:
+```shell
+scp {ADMIN_USER}@{DOMIBUS_HOSTNAME}:/opt/{DOMIBUS_SERVER_DIRECTORY}/domibus/keystores/{DOMIBUS_ACCESS_POINT}.cer /path/on/your/personal/computer
+```
+>**Note**: We consider you created your **`{DOMIBUS_SERVER_DIRECTORY}`** inside the **`/opt/`** folder like suggested earlier. If not, please adjust the command to reflect the exact location of your **`{DOMIBUS_SERVER_DIRECTORY}`**
+
+This step ensures that you have a local copy of the certificate file for further actions.
+
+###:construction: under construction :construction:
 
 ## 3 - Domibus Properties
-In the file **`{DOMIBUS_DOCKER_DIRECTORY}/domibus/domibus.properties`**, locate the section labeled `Keystore/Truststore (Single Tenancy)` and set the passwords you configured on the previous step:
+:globe_with_meridians:
+In the file **`{DOMIBUS_SERVER_DIRECTORY}/domibus/domibus.properties`**, locate the section labeled `Keystore/Truststore (Single Tenancy)` and set the passwords you configured on the previous step:
 
 ```properties
 # ---------------------------------- Keystore/Truststore (Single Tenancy) -----------------------
@@ -176,7 +237,7 @@ domibus.security.key.private.password={PRIVATE_KEY_PASSWORD}
 ...
 
 #The password used to load the trustStore
-domibus.security.truststore.password={TRUSTORE_PASSWORD}
+domibus.security.truststore.password={TRUSTSTORE_PASSWORD}
 ```
 
 In the `Security` section of the file, uncomment and enable security by setting the following property to the value `false`:
@@ -191,15 +252,18 @@ domibus.auth.unsecureLoginAllowed=false
 While you might consider creating a `PKCS12` KeyStore, please be aware that it currently appears to be non-functional.
 
 ## 4 - Users Credentials
+:globe_with_meridians:
 Within the directory or any of its subdirectories of the **`{DOMIBUS_SERVER_DIRECTORY}`**, restart your Domibus server by doing the command:
 ```shell
 docker compose restart
 ```
-From your browser, access to your Domibus server with the following URL:
+From the browser of your PC, access to your Domibus server with the following URL:
+:computer:
 ```http
 http://{DOMIBUS_HOSTNAME}:{DOMIBUS_PORT}/domibus
 ```
 ### A - Dashboard Users
+:computer:
 Access the Domibus Admin Console using the default credentials:
 ```
 Username: admin
@@ -212,6 +276,7 @@ You have the option to change this password at the top right of the console.
 Alternatively, user management can be performed in the `Users` section of the left navigation bar.
 
 ### B - Plugin Users
+:computer:
 A plugin user, specifically utilized for eDelivery message exchange through our Connector API, can be added in the `Plugin Users` section. To do so, navigate to this section, click on `+ New`, and provide the desired username, password, and role.
 
 Make sure that you save your modification.
@@ -222,8 +287,10 @@ For the French-Connector, you might create a user named `frc_user`.
 ![plugin_user](/img/domibus/image3.png)
 
 ## 5 - Processing Modes
-Processing Modes _PModes_ are used to configure Access Points. The PMode parameters are loaded into the Access Point via an XML file.
-Begin by downloading the PMode template file [pmode.xml](https://drive.google.com/file/d/1onmrwqKYcVeTwSZLzzD0WrYd9ndJbLxW/view?usp=drive_link) and replacing the variables with the appropriate placeholder values. Upload the modified file under:
+:computer:
+Processing Modes _PModes_ configure Access Points by loading parameters via an XML file. Please perform this task from your personal computer
+
+Start by downloading the PMode template file [pmode.xml](https://drive.google.com/file/d/1onmrwqKYcVeTwSZLzzD0WrYd9ndJbLxW/view?usp=drive_link). After downloading, replace the variables in the file with the appropriate values for your configuration. Once modified, proceed to upload the file under:
 
 **`PMode` → `Current`**
 
@@ -240,12 +307,12 @@ Click on `+ New`
 Create a name such as `europe_ap` and set the endpoint with the `/domibus/services/msh` path.
 
 ```http
-http://51.159.133.186:8080/domibus/services/msh
+http://<EU-HOSTNAME>:<EU-PORT>/domibus/services/msh
 ```
 ![party](/img/domibus/image4.png)
 
 >**Note**:
-The host `51.159.133.186:8080` is the EU Domibus server's address. If you add another Access Point, include the address of that Domibus server.
+You can include the IP address of the specific Access Point you wish to establish communication with. However, in our scenario, it's essential to add only the IP address of the EU Access Point, which serves as the central hub.
 
 Import the [EU Access Point Certificate](https://drive.google.com/file/d/1jduYescq5XkJ8PPoMamWBDjOFoAY9GNO/view?usp=drive_link)
 
@@ -266,10 +333,10 @@ You are now able to communicate with the Access Point you just added.
 Verify on the `Parties` tab to ensure that all parties are configured correctly.
 
 # Testing Configuration
-Congratulations on setting up your Domibus server. Let's conduct some tests to ensure everything is working correctly.
+Congratulations on successfully setting up your Domibus server. To ensure everything is functioning correctly, let's proceed with testing. Please run all the tests on your personal computer :computer:
 
 ### 1 - Console Monitoring test
-Navigate to the `Connection Monitoring` section and try sending a message to your own Access Point and to `europe_ap`. If the status shows as green for both, your Domibus server is ready for message exchange.
+In the Domibus Console, navigate to the `Connection Monitoring` section and try sending a message to your own Access Point and to `europe_ap`. If the status shows as green for both, your Domibus server is ready for message exchange.
 
 ![monitoring](/img/domibus/image6.png)
 
@@ -277,7 +344,7 @@ Navigate to the `Connection Monitoring` section and try sending a message to you
 To perform testing with SoapUI, follow these steps:
 
 ##### A - Install SoapUI:
-- Ensure you have the latest version of [SoapUI](https://www.soapui.org/) installed.
+- Ensure you have the latest version of [SoapUI](https://www.soapui.org/) installed on your PC.
 
 ##### B - Download Domibus Sample:
 - Download the Domibus sample configuration for testing from [here](https://ec.europa.eu/digital-building-blocks/wikis/display/DIGITAL/Domibus).