Add environment setup guide and troubleshooting section

docs/Troubleshooting.md

@@ -0,0 +1,111 @@
+# Troubleshooting Guide: Canis Major Integration Tests
+
+## Common Issue: Build Failure During Integration Tests
+
+This guide addresses the most common issue encountered with the Canis Major adapter: build failure when running integration tests. If you experience a build failure while executing the `mvn clean test` command, follow these steps to resolve the issue.
+
+### Solution: Updating 'NGSI Address' environment variable
+
+1. **Check the IP Address of the Canis Major Container**
+
+   Run the following command to obtain the IP address of the Canis Major container:
+
+   ```bash
+   docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' <canis_major_container_name_or_id>
+   ```
+
+   Replace `<canis_major_container_name_or_id>` with the actual name or ID of your Canis Major container.
+
+2. **Run Tests with Updated NGSI Address**
+
+   Navigate to the `/it` folder and execute the following command:
+
+   ```bash
+   NGSI_ADDRESS=<ip_address_of_canis_major_container>:4000 mvn clean test
+   ```
+
+   Replace `<ip_address_of_canis_major_container>` with the IP address obtained in step 1.
+
+### Command Breakdown
+
+The command used in step 2 consists of two main parts:
+
+1. **Environment Variable Assignment**:
+   `NGSI_ADDRESS=<ip_address_of_canis_major_container>:4000`
+   - Sets the `NGSI_ADDRESS` environment variable.
+   - Specifies the address of the ETSI NGSI-LD API of the Canis Major.
+
+2. **Maven Command**:
+   `mvn clean test`
+   - `clean`: Deletes the `target` directory, ensuring a clean build environment.
+   - `test`: Compiles the source code and runs all unit tests in the project.
+
+By using this approach, you ensure that the integration tests are executed against the correct Canis Major endpoint, which should resolve the build failure issue.
+
+If you continue to experience problems after following the provided steps, please open an issue in the GitHub repository with detailed information about the error you are encountering.
+
+## Common Issue: Problem to execute the integration test again.
+
+If you try to execute twice the integration tests, you will receive an error message like the following:
+
+```bash
+[INFO] -------------------------------------------------------
+[INFO] T E S T S
+[INFO] -------------------------------------------------------
+[INFO] Running it.RunCucumberTest
+
+Scenario: A test-store, created at orion-ld, is available through CanisMajor. 
+ # it/store_transactions_on_entities_in_canis_major.feature:4
+
+ Given CanisMajor is running and available for requests.
+
+ # it.StepDefinitions.setup_canis_major_in_docker()
+
+ And Vault is configured as a signing endpoint.
+
+ # it.StepDefinitions.configure_ethereum_plugin_vault()
+
+ And Franzi is registered in vault.
+
+ # it.StepDefinitions.register_franzi_in_vault()
+
+ And Mira is registered in vault.
+
+ # it.StepDefinitions.register_mira_in_vault()
+
+ When Franzi creates the test-store.
+
+ # it.StepDefinitions.create_test_store()
+
+ Then Only one transaction should be persisted for the entity.
+
+ # it.StepDefinitions.assert_only_one_transaction()
+
+org.awaitility.core.ConditionTimeoutException: Condition with it.StepDefinitions was not
+
+ fulfilled within 15 seconds.
+
+at org.awaitility.core.ConditionAwaiter.await(ConditionAwaiter.java:165)
+
+at org.awaitility.core.CallableCondition.await(CallableCondition.java:78)
+
+at org.awaitility.core.CallableCondition.await(CallableCondition.java:26)
+
+at org.awaitility.core.ConditionFactory.until(ConditionFactory.java:895)
+
+at org.awaitility.core.ConditionFactory.until(ConditionFactory.java:864)
+
+at it.StepDefinitions.assert_only_one_transaction(StepDefinitions.java:559)
+
+at ✽.Only one transaction should be persisted for the entity.
+
+(classpath:it/store_transactions_on_entities_in_canis_major.feature:10)
+
+ And The transaction to persist test-store can be read through CanisMajor.
+ # it.StepDefinitions.get_test_store()
+```
+
+This is produced by the intent to save again the information of the users' credentials in the Vault.
+
+### Command Breakdown
+Stop the docker compose and start again to ensure the Vault's content is clean before executing the integration tests again.

docs/setup.md

@@ -0,0 +1,41 @@
+# Prerequisites for Running Canis Major
+
+
+This document outlines the prerequisites to running the Canis Major adapter without issues. The setup has been tested on an Ubuntu 22.04.1 LTS virtual machine running on FIWARE Lab. For more information on [FIWARE lab](https://www.fiware.org/developers/fiware-lab/) check the official documentation.
+
+#### Java setup
+
+The Canis Major adaptor is currently functional using Java 21. Here are the specific details of the Java version used:
+
+- **Version**: OpenJDK 21.0.5
+- **Release Date**: October 15, 2024
+- **Distribution**: OpenJDK (Open Java Development Kit)
+To install OpenJDK 21 on Ubuntu 22.04, the following command could be used:
+
+````bash
+sudo apt update
+sudo apt install openjdk-21-jdk
+````
+To verify the Java installation:
+````bash
+java -version
+````
+
+#### Docker Setup
+
+Docker is required to run Canis Major. The following versions have been tested and confirmed to work:
+
+- **Docker Version**: 27.3.1, build ce12230
+- **Docker Compose Version**: v2.29.7
+
+For a proper docker and docker-compose installation follow the instructions provided in the official [documentation](https://docs.docker.com/engine/install/ubuntu/).
+
+To verify the docker and docker-compose installations:
+```bash
+docker --version
+docker-compose --version
+```
+
+Proper setup is crucial for the proper functioning of the Canis Major adapter and for avoiding any issues when testing it.
+
+