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.

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.

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.

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. Activate the service definition:

    Execute systemctl daemon-reload

2. Start OpenEMS Backend

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

  1. (Re)start OpenEMS systemd service.

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

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