7 OpenEMM Deployment
7.1 Download
We recommend to download the deployment & runtime package of OpenEMM from https://www.agnitas.de/en/download/openemm-binaries/. This package provides an installer tool for the backend and frontend code and eases installation, updates, administration and maintenance of OpenEMM significantly.
Of course, you can also download the source code of OpenEMM from GitHub at https://github.com/agnitas-org/openemm and compile and deploy the software manually yourself. See the build instructions at the end of the OpenEMM wiki page at https://wiki.openemm.org.
7.2 OST (OpenEMM Support Tool)
Download the OpenEMM runtime tarball (file name: openemm-runtime-<release>.tar.gz) to /home/openemm to create the deployment and runtime environment for OpenEMM. Change to user openemm, unpack the tarball and start it with
At the first start OST checks for certain packages and settings and offers to change them.
While OpenEMM needs Python 3.11 or higher to work, OST itself is fine with older versions 3 of, i.e. the python3 package of the operating system would be sufficient.
OST is an interactive command line tool, which should be your preferred way to check, configure and update various components of OpenEMM.
Current menu: Main
Please choose (Blank => Quit):
1. Show OpenEMM status
2. Configuration
3. Database Maintenance
4. Security
5. Install or update package from AGNITAS Website
6. Install or update package from local file
7. Install or update package from AGNITAS Cloud
8. Show update history
9. Switch OpenEMM version
10. Restart OpenEMM
11. Send configuration and log files in email
0. Quit
>
At launch time OST checks if kernel parameters in /etc/security/limits.conf are big enough and, if not, offers to change them. To be able to change this file, you need to start OST as user root. After the change of the kernel parameters, you have to reboot the server.
At launch time OST also checks your software stack and offers to install required packages (including Java and Tomcat) and to set environment variables
- JAVA_HOME for Java (default path: /usr/lib/jvm/java)
- CATALINA_HOME for Tomcat (default path: /home/openemm/opt/tomcat/)
- PROXY to communicate with the Internet (optional, default: left empty)
These parameters will be written to file setenv.sh in directory /home/openemm/bin/.
If one of these tools is not available on your server yet, OST offers to install it for you.
OST helps you to set up and configure a database connection (file dbcfg) including database user and password. In menu Configuration → Change database configuration you can enter the required properties like database type ("mariadb"), database name ("openemm"), database user (suggestion: "openemm") and your database password. Do not forget to confirm your changes with “save”!
If the database configuration file dbcfg does not exist in directory /home/openemm/etc/, it is also created from scratch. A valid dbcfg file looks like this:
openemm: dbms=mariadb, host=localhost, name=openemm, user=openemm, password=<password>, jdbc-connect=jdbc:mariadb://localhost/openemm?zeroDateTimeBehavior=convertToNull&useUnicode=true&characterEncoding=UTF-8, jdbc-driver=org.mariadb.jdbc.Driver
Please make sure, that every comma separating a key-value pair is followed by a blank. Only this format makes sure that you can use a comma within a password or other values.
If the OpenEMM database and its user does not exist, OST offers to set it up for you after you have entered the properties mentioned above. The empty OpenEMM database will be filled later during installation of the OpenEMM code package.
If for whatever reason the creation of the database user for OpenEMM does not work, you can create the user manually with
mysql -u root -p
CREATE USER 'openemm'@'localhost' identified by '<password>';
GRANT ALL PRIVILEGES ON openemm.* TO 'openemm'@'localhost' ;
GRANT SELECT ON mysql.proc TO 'openemm'@'localhost';
GRANT RELOAD ON *.* TO 'openemm'@'localhost';
GRANT SUPER ON *.* TO 'openemm'@'localhost';
FLUSH PRIVILEGES;
Please replace placeholder <password> with a strong password.
You need the global permissions SELECT ON mysql.proc to read Stored Procedures, RELOAD to be able to flush the privileges and SUPER to be able to create database triggers. If you are not able to get permission SUPER, as a workaround you can set
in section [mysqld] of your database configuration file my.cnf.
7.2.1 Menus of OST
Menu "Show EMM status" starts a brief health check of the OpenEMM configuration on the current server and checks the integrity of the files via their checksums.
Menus "Configuration" help you to check, change or create certain settings of your OpenEMM configuration without having to deal directly with the OpenEMM database or configuration files:
Current menu: Configuration
Please choose (Blank => Back to Main):
1. Configure basic environment (Java, Tomcat, Proxy)
2. Change configuration of database connection
3. Change basic configuration
4. Change layout images
5. Change client/account configuration
6. Change jobqueue configuration
0. Back to Main
>
Sub-menu Change basic configuration offers you to define domain names for various EMM services:
| Domain Name | Name of Parameter |
|---|---|
| OpenEMM GUI | system.url |
| Mailloop Service | system.defaultMailloopDomain |
| Redirect Service | system.defaultRdirDomain |
| Statistics Service | birt.url |
| Statistics Service | birt.url.intern |
| Webservices | webservices.url |
When you call this sub-menu the first time and no value is set yet, you are asked to enter the FQDN of your OpenEMM server, including the access protocol (HTTP or HTTPS). Based on your input the values of the parameters mentioned in the table above are prefilled. You can change those values later at any time.
Property birt.url.intern should be set to value http://localhost:8080/birt in any case.
You should also configure various email addresses for mails from OpenEMM and notifications:
| Name of Parameter | Description |
|---|---|
| mailaddress.sender | sender address for all frontend emails (like reports), also used for 2FA and error mails |
| mailaddress.replyto | reply-to address for all frontend emails (like reports), also used for 2FA and error mails |
| mailaddress.bounce | bounce address for all frontend emails (like reports), also used for 2FA and error mails (optional) |
| mailaddress.info.cleaner | email address that gets notifications if a nightly DB cleaning process did not finish in time |
| mailaddress.error | email address for EMM error notifications like DB connection error |
| mailaddress.frontend | email address that gets notifications for user form errors and for action script errors |
| mailaddress.upload.database | email address that gets notifications that a new file was uploaded in the upload menu |
| mailaddress.upload.support | email address that gets any instructions included in a file upload |
| mailaddress.report_archive | email address that gets report mails to be archived |
| mailaddress.support | email adress that gets messages sent via button "report a problem" |
| mailaddress.feature_support | email adress that gets messages sent via button "suggest a feature" |
Sub-menu Change layout images offers you the possibility to change the logos of EMM for white-labeling. Just enter the file name of the logo you want to change and enter path and file name of the replacement:
favicon.ico (the icon often displayed in the browsers tab,
besides the title)
logo.svg (small logo in the webapplication above the
menu and login mask)
logo.png (an alternative to the SVG logo)
edition_logo.png (logo in login mask)
report_logo.png (logo used inside pdf reports)
Please choose layout image to replace (Blank => Back):
> logo.svg
Please enter new image filepath for replacement of 'logo.svg':
> /home/user/image.png
Sub-menu Change client/account configuration offers you to change the domain names for the mailloop service and redirect service separately. Also, you should define an email address for property contact_tech, because OpenEMM will send certain warnings to this email address.
Menu Database Maintenance offers a backup and restore of the database present on the server.
With menu "Security" you can set a new password for admin user emm-master if you select option "Create new initial 'emm-master' password". You may use this option also in case you have forgotten the password for user emm-master.
Also, you can use option Configure TLS certificate (https) to customize Tomcat's configuration file server.xml with your TLS certificate files so that OpenEMM can be accessed by the HTTPS protocol. If you want to know more about the details, have a look at chapter Apache NIO Connector.
Menu "Install or update package from ..." supports you in downloading packages of a new OpenEMM release from various sources. Please be aware that you have to start OST as user root to be able to install or update a backend service. If you want to load a file from an external source (AGNITAS), make sure that the server OST is running on, is able to access this source. Otherwise download the file first with a different device, copy it to your server and install it as local file.
If you need to know which services and versions of OpenEMM were active at what time in the past, menu Show update history provides a list of all available services, their versions and the exact startup times.
Menu "Switch OpenEMM version" lets you roll back to a former version of an OpenEMM service or roll forward to a later version. However, if you switch back not to an older patch level (last 3 digits of the version number), but to an older minor or major version (like going back from 20.10 to 20.04), please be advised that the database schema is not rolled back and, therefore, some feature may not work properly because it wants to use a database field that does not exist any longer in the new database schema.
After a change of version or after an OpenEMM service update, use menu "Restart OpenEMM" to restart the OpenEMM installation on the current server (frontend and backend services, if available).
Menu "Send configuration and log files in email" helps you to create an email which sends all important OpenEMM configuration information to an email address of your choice for diagnostic purposes or as a backup. For that reason, the tool collects certain configuration and log files from the current server as well as the content of database configuration tables of your OpenEMM installation and sends them out as zipped and password-protected attachment. Since this attachment can become quite big, make sure that the receiving email address is able to handle this payload.
If OST reports an error during operation, re-start OST with option -debug and repeat the operation. In this case OST will show a stacktrace for the error, which will give you a hint what went wrong.
7.3 OpenEMM Deployment
For the deployment of the openemm code tarball you have to start OST (OpenEMM Support Tool) as user root, because some files of the tarball have to be deployed with root permissions:
Use menu Install or update package from AGNITAS website to install the openemm code package. As first step, the menu offers to install an update of the runtime package, if a later version is available. Opposed to upgrading to a new major version of OpenEMM, an update to a new runtime version is always recommended.
Answer “no” to all downloads offers until the openemm code package is offered (if you started OST as user root). If an upgrade of a major version of OpenEMM is available (like 21.04) this upgrade opportunity is offered first. However, you should not blindly accept it if you are working on a production system (see section Test and Production System below).
During Deployment of the openemm code tarball several new directories and symlinks will be created in directory /home/openemm/. Also, the OpenEMM database is automatically populated with its initial content.
If you do not want to install or update the code of OpenEMM, you can start OST as user openemm:
7.4 Configuration
After deployment of the OpenEMM code but before launching it with the restart menu, use menu Configuration → Change basic configuration to set up and change the configuration of OpenEMM. Note: It is possible to launch OpenEMM without adapting the configuration, but in this case not all features of the software will work properly.
With OpenEMM 20.04 all configuration properties have been migrated from files emm.properties, emm-ws.properties and Mailgun.ini to the OpenEMM database. Therefore, you do not change these files any longer but the corresponding database entries listed in the sub-menu mentioned above. The advantage of the migration from files to database is, that further updates of OpenEMM do not overwrite any individual settings you might have made.
Sub-menu Change basic configuration asks you to enter the full URL of your server including protocol (http or https). From this value it deviates the settings for various essential properties.
Sub-menu Change client/account configuration offers you to change the redirect domain and the mailloop domain. These value are pre-filled by the basic configuration and you should change those values only if you know what you are doing:
- Set rdir_domain to the protocol and FQDN of your server, for example https://openemm.example.com. This domain will be used in all measurable links to redirect them through OpenEMM. This property must include the appropriate protocol.
- Set mailloop_domain to the domain of your sender address. The domain for the mailloop service must be different from the name of your OpenEMM server. It usually is a domain whose MX record points to your OpenEMM server. For example the FQDN of your sender address is mailing.example.com and its MX record points to openemm.example.com which is the address of your OpenEMM server. In this case, use domain mailing.example.com as domain for the sender address of your mailings. (There are other ways for configuration, described in section Mailloop Configuration.) If you do not configure the mailloop service, OpenEMM can only process instant bounces, i.e. you will not be able to catch all bounces. This property must not include any protocol.
Finally, create an initial password for admin user "emm-master" in menu Security → Create new initial 'emm-master' password. Write down the generated password and use user "emm-master" and this initial password later for your first login in the GUI of OpenEMM. At first login, you will be prompted to change your password to a new one of your choice. In case you forget your password for the admin user at a later time, you can always use this menu of OST (OpenEMM Support Tool) to set a new password.
7.5 Startup
Launch OpenEMM with menu Restart OpenEMM of OST. Experts may have a look at the Tomcat log during startup with
to check for any warnings or error messages. Be patient, because the startup process will take a minute or two.
After OpenEMM has been launched successfully, point your browser to your OpenEMM server and log in with user “emm-master” and the initial password you just created. OpenEMM will ask you to change the initial password to a new one of your choice.
If you want to install the context-sensitive online help feature of OpenEMM (including the user manual with about 500 pages), visit
- https://www.agnitas.de/en/download/openemm-manual/ (English)
- https://www.agnitas.de/download/openemm-handbuch/ (German)
to get the download link for the manual package. You can use OST’s menu Install or update package from AGNITAS Cloud to install the documentation.
7.6 Test and Production System
If OpenEMM is an important software for you (and we hope it is!) we recommend to set up a separate test system alongside your production system. This should be no probem for you, because the complete software stack for OpenEMM is open source and you do not have to pay a dime for the additional instance.
You can create a copy of your OpenEMM production database with menu Database Maintenance → Backup MariaDB database of OST. On your test system you should only create the empty OpenEMM database with menu Configuration → Change configuration of database connection. Now you can set up the database copy of your production system with menu Database Maintenance → Restore MariaDB database. But make sure that both systems use the same DBMS version to avoid any trouble.
After that, you only have to adjust the properties containing the server URL in menu Configuration → Change basic configuration, because they have been copied from your production database as well. Now you are ready to use your test system to try out different configuration settings, to test database backup and restore or to test an upgrade to a new major OpenEMM version – all that before applying any change to your precious production system.
7.7 Rendering of Thumbnail Images and PDF Documents
If you want to generate good-looking thumbnails and PDF files in the OpenEMM GUI, the OpenEMM server needs the installation of some more packages:
RHEL:
dnf install gcc-c++ mesa-libgbm atk at-spi2-atk libXcomposite libXdamage libXrandr libXrender libxkbcommon pango
dnf module reset nodejs
dnf module enable nodejs:20
dnf install nodejs
SLES:
zypper install gcc-c++ libgbm1 libgbm-devel
SUSEConnect -p sle-module-web-scripting/15.4/x86_64
zypper install nodejs18
Finally, switch to user openemm, change to directory /home/openemm/webapps/emm/WEB-INF and install the NPM package puppeteer via port 443 (HTTPS) from the NPM server (operated by GitHub/Microsoft):
This means, that the OpenEMM server needs access to the Internet during deployment!
Furthermore, puppeteer must be able to access the browser frontend of OpenEMM from localhost. Therefore, make sure that your firewall rules do not block access of port 80 (HTTP) or 443 (HTTPS) from localhost.