#####################
Backend
#####################

.. contents::
  :local:
  :depth: 1

  
Introduction
==============
Developing a backend component for a web application depends on the specific requirements and functionalities of this application. 
In the scope of aerOS, that considers the aerOS Basic Services as a suite of lightweight microservices (including the potential workloads to be orchestrated  
in the computing continuum), it is evident that heavier computing processes (e.g., data processing) must be removed from the unique web application that aims to 
act as the management entry point to the continuum.

Thus, removing this logic from the frontend component of the portal allows to develop the frontend to just react to user actions and obtain the needed data in 
the expected format to be then efficiently interpreted, as well as avoiding some security issues like the well-known CORS. 
Therefore, the backend component acts as a middleware between the web page and third-party APIs

Finally, although this component can work as an independent REST API, it is intended to be used as the backend of 
the :doc:`aerOS Management Portal Frontend </monitoring/management/portal/front>`.

User guide
==========
The backend of the Management Portal an work as an independent REST API, but it has been designed to be deployed along with the frontend of the portal.

Prerequisities
==============
This aerOS Basic Services are needed to cover all the functionalities provided by the backend:

- Keycloak
- OpenLDAP
- Orion-LD
- Entrypoint Balancer & aerOS orchestrator

Configuration options
=====================
This backend can be configured by using these environment variables:

- *LOG_LEVEL*: logging level of the application itself (ERROR, WARN, INFO, DEBUG, or TRACE).
- *LDAP_LOG_LEVEL*: logging level of LDAP modules of the application (it includes the Spring Data LDAP 3 framework).
- *SECURITY_LOG_LEVEL*: logging level of the Spring Security 6 framework (ERROR, WARN, INFO, DEBUG, or TRACE).
- *ORION_URL*: URL of the Orion-LD instance (including the path to its *entities* endpoint) of the entrypoint domain.
- *HLO_FE_URL*: full URL of the REST API (FE endpoint) of the of the aerOS HLO's Storage Engine component.
- *ENTRYPOINT_BALANCER_URL*: full URL of the Entrypoint Balancer.
- *KEYCLOAK_URL*: URL of the Keycloak instance of the entrypoint domain.
- *KEYCLOAK_REALM*: realm of the Keycloak instance of the entrypoint domain.
- *LDAP_URL*: URL of the LDAP instance of the entrypoint domain.
- *LDAP_USERNAME*: username of the LDAP instance of the entrypoint domain.
- *LDAP_PASSWORD*: password of the LDAP instance of the entrypoint domain.


Developer guide
===============
The Backend of the aerOS Management Portal has been developed a **Spring Framework 6** application, starting the project with **Spring Boot 3** 
and using some complementary libraries such as **Spring Security**, **Spring Cloud** and **Spring LDAP**.

Minimum prerequirements for the local development machine:

- `Java JDK 21 <https://www.oracle.com/es/java/technologies/downloads/#java21>`__
- `Apache Maven 3.6 <https://maven.apache.org/download.cgi>`__

The recommended IDE to develop this component is `IntelliJ IDEA <https://www.jetbrains.com/idea/>`__ but other alternatives such as Eclipse Java IDE and VSCode can be used as well.

Now, the application can be run using the selected IDE. It will run by default in the port 8080.

Finally, the Spring application can be configured through the modification of the *src/main/resources/application.properties* file:

.. code:: properties

  # Logging
  logging.level.eu.aerosproject=${LOG_LEVEL:INFO}
  logging.level.org.springframework.ldap=${LDAP_LOG_LEVEL:INFO}
  logging.level.org.springframework.security=${SECURITY_LOG_LEVEL:INFO}
  # logging.level.org.springframework.web.socket=${WEBSOCKET_LOG_LEVEL:INFO} # only for STOMP WebSockets

  # aerOS configuration
  aeros.entrypoint-balancer=${ENTRYPOINT_BALANCER_URL:http://entrypoint-balancer.default.svc.cluster.local:8080}
  aeros.hlo-fe=${HLO_FE_URL:http://hlo-fe-service.default.svc.cluster.local:8081}
  aeros.orion-ld=${ORION_URL:http://orion-ld-broker.default.svc.cluster.local:1026/ngsi-ld/v1/entities}

  # External LDAP directory configuration
  spring.ldap.urls=${LDAP_URL:ldap://openldap.default.svc.cluster.local:389}
  spring.ldap.username=${LDAP_USERNAME:cn=admin,dc=example,dc=org}
  spring.ldap.password=${LDAP_PASSWORD:<Password>}


Packaging into a JAR file
-------------------------
This application can be packaged into a Java JAR file using Maven. 
This JAR file will be created inside the *target* folder named as *management-portal-backend-{POM-application-version}.jar*, for instance, 
*management-portal-backend-1.1.0.jar*. The application version is specified in the line 13 of the *pom.xml* file.

In order to package the application into a JAR file, run:

.. code:: bash

  mvn clean compile package


Build a container image
-----------------------
First, package the application into a JAR file. Then, use the included *Dockerfile* to build the container image:

.. code:: bash

  docker build -t registry.gitlab.aeros-project.eu/aeros-public/common-deployments/management-portal/backend:<app-version> --build-arg APP_VERSION=<app-version> .

For instance:

.. code:: bash

  docker build -t registry.gitlab.aeros-project.eu/aeros-public/common-deployments/management-portal/backend:1.1.0 --build-arg APP_VERSION=1.1.0 .


Authors
=======
Universitat Politècnica de València