Deploy OpenEMS Backend on Debian Linux

This chapter explains how OpenEMS Backend can be deployed on a Debian Linux server. Similar techniques will work for other operating systems as well.

The involved components (Edge.Manager, Backend.Edge.App) and the available deployment options are described in Backend Architecture. This guide covers the single-server setup, where the Backend and the Backend Edge Application run on the same host as two separate services.

1. Prepare operating system environment

It is recommended to run every service on a server with limited permissions. This example runs OpenEMS Backend with user "root" which is a bad idea for a production server!

1.1. Check JAVA version

Ensure that a JRE version 21 or later is installed. We recommend using temurin-21-jre

For detailed installation instructions, visit Adoptium Installation Guide.

If you are using an ARM32 device, download temurin-21-jre-armhf_21.0.6+2.deb directly from OpenEMS.

1.2. Create an application directory

Create the directory /opt/openems-backend. This is going to be the place, where we put the JAR file.

Execute mkdir /opt/openems-backend.

Create the directory /opt/openems-backend-edge as well. This is going to be the place, where we put the JAR file of the Backend Edge Application.

Execute mkdir /opt/openems-backend-edge.

1.3. Create a config directory

Create the directory /opt/openems-backend/config.d. This is going to be the place, where all the bundle configurations are held.

Execute mkdir /opt/openems-backend/config.d.

Create the directory /opt/openems-backend-edge/config.d for the Backend Edge Application as well.

Execute mkdir /opt/openems-backend-edge/config.d.

1.4. Create a systemd service definition

The systemd 'Service Manager' manages system processes in a Debian Linux. We will create a systemd service definition file, so that systemd takes care of managing (starting/restarting/…​) the OpenEMS Backend service.

  1. Create and open the service definition file.

    Execute nano /etc/systemd/system/openems-backend.service

  2. Paste the following content:

    [Unit]
Description=OpenEMS (1)
After=network.target (2)

[Service]
User=root (3)
Group=root
Type=simple (4)
WorkingDirectory=/opt/openems-backend
ExecStart=/usr/bin/java -XX:+ExitOnOutOfMemoryError -Dfelix.cm.dir=/opt/openems-backend/config.d -Djava.util.concurrent.ForkJoinPool.common.parallelism=100 -jar /opt/openems-backend/openems-backend.jar (5)
SuccessExitStatus=143 (6)
Restart=always (7)
RestartSec=10 (8)

[Install]
WantedBy=multi-user.target
    1 The name of the service.
    2 The service is allowed to start after network is available (e.g. to be able to access devices via ethernet connection)
    3 It is run as user 'root' to have access to all devices. It is recommended to change this for productive systems.
    4 OpenEMS Backend uses a "simple" process fork.
    5 The start command. It uses the Java JRE, sets the config directory to /opt/openems-backend/config.d, sets a parallelism value for ForkJoinPool - this depends on the number of OpenEMS Edge devices you expect to connect - and runs the jar file at /opt/openems-backend/openems-backend.jar
    6 In contrast to what systemd expects, Java exits with status 143 on success.
    7 Systemd always tries to restart OpenEMS Backend once it was quit.
    8 Systemd waits 10 seconds till the next restart.

  3. Press Ctrl + x to exit and y to save the file.

  4. Create and open the service definition file of the Backend Edge Application.

    Execute nano /etc/systemd/system/openems-backend-edge.service

  5. Paste the following content:

    [Unit]
Description=OpenEMS Backend Edge Application (1)
After=network.target

[Service]
User=root
Group=root
Type=simple
WorkingDirectory=/opt/openems-backend-edge
ExecStart=/usr/bin/java -XX:+ExitOnOutOfMemoryError -Dfelix.cm.dir=/opt/openems-backend-edge/config.d -jar /opt/openems-backend-edge/openems-backend-edge.jar (2)
SuccessExitStatus=143
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
    1 The name of the service. The Backend Edge Application is the process that the OpenEMS Edge devices connect to (see Backend Architecture).
    2 Same as the OpenEMS Backend service, but using the JAR file and config directory of the Backend Edge Application.

  6. Press Ctrl + x to exit and y to save the file.

  7. Activate the service definitions:

    Execute systemctl daemon-reload

2. Start OpenEMS Backend

To update the OpenEMS JAR files at the target device, it is required to copy the JAR files from your build directory to /opt/openems-backend/openems-backend.jar and /opt/openems-backend-edge/openems-backend-edge.jar on the server. Afterwards it is required to restart the systemd services

  1. (Re)start OpenEMS systemd services.

    Execute systemctl restart openems-backend openems-backend-edge --no-block; journalctl -lfu openems-backend -fu openems-backend-edge

    The command restarts both services (systemctl restart openems-backend openems-backend-edge) while not waiting for the OpenEMS startup notification (--no-block). Then it directly prints the OpenEMS system logs (journalctl -lfu openems-backend -fu openems-backend-edge).

3. Backend configuration

3.1. Edge Manager

  1. Open the Apache Felix Web Console Configuration .

    The Apache Felix Web Console for OpenEMS Backend is started on port 8079 by default. This is configured using the org.osgi.service.http.port setting in BackendApp.bndrun.

    Login with username admin and password admin.

  2. Configure the Edge Manager service.

    The Edge Manager is the service that manages the connections of the Backend.Edge.App instances (see Backend Architecture).

    The relevant configuration parameters are:

    • Port: the port of the websocket server that the Backend.Edge.App instances connect to (default 8083)

    • Number of Threads: the pool size, i.e. the number of threads dedicated to handle the tasks (default 10)

      For the single-server setup of this guide the default values can be accepted. Click Save.

3.2. Backend Edge Application

The Backend Edge Application runs as a separate process with its own Apache Felix Web Console on port 8078.

  1. Open the Apache Felix Web Console Configuration .

    Login with username admin and password admin.

  2. Configure the Backend Edge Application service.

    The Backend Edge Application is the proxy process that the OpenEMS Edge devices connect to (see Backend Architecture).

    The relevant configuration parameters are:

    • Component-ID: a unique ID of this Backend Edge Application (default edges0)

    • Uri: the connection Uri to the OpenEMS Backend Edge-Manager (default ws://localhost:8083)

    • Port: the port of the websocket server for OpenEMS Edge Controller.Api.Backend (default 8081)

    • Number of Client-Threads / Number of Server-Threads: the pool sizes handling the Client and Server tasks (default 10 each)

      For the single-server setup of this guide the default values can be accepted. Click Save.

In this setup, the Backend Edge Application connects to the Edge Manager of the OpenEMS Backend process via the loopback interface using the default Uri ws://localhost:8083.