User Tools

Site Tools


start

OpenEMM 2019 Install & Configuration Wiki (BETA)

Latest Version of OpenEMM 2019 BETA: Runtime: 19.04.081, Backend: 19.04.000.222, Frontend: 19.04.000.291

OpenEMM 2019 BETA is not ready for productive use, yet. But with downloading and testing you can make yourself familiar with the software, and we kindly ask you to help us with your feedback to improve the documentation, installation, configuration and administration of OpenEMM 2019!

Please leave your questions and comments in the OpenEMM forum at forum.openemm.org.

1. Introduction

OpenEMM is a professional open source software for email marketing and automation. If you want to automate your email communication, OpenEMM is the right choice for you.
The first version of OpenEMM was published in 2006. The source code of the current version OpenEMM 2019 will be published at GitHub, using the popular open source license AGLPv3, as soon as the final version of OpenEMM 2019 is available.

2. Requirements

  • RedHat 7 or CentOS 7 64 bit (with VirtualBox: Windows, macOS or any other Linux)
  • Java Open JDK 8
  • Apache Tomcat 9
  • Python 2.7 (3.x with a future version)
  • MySQL 5.6 or 5.7, or MariaDB 10.1, 10.2 or 10.3
  • Sendmail 8.10 or later, or Postfix 2.6 or later
  • wkhtmltox 0.12.2.1 or later
  • for HTTPS support: Apache Tomcat Native Library

3. Preparations

OpenEMM consists of 3 packages:

  1. the deployment and runtime environment (openemm-gui-runtime-19.04.*.tar.gz)
  2. backend code for dispatch of mails, management of bounces and replies (openemm-backend-19.04.000.*.tar.gz)
  3. frontend code with GUI, statistics and webservices (openemm-frontend-19.04.000.*.tar.gz)

Unless noted otherwise below, use user “root”.

Packages of Operating System

Install the required packages:
(this example uses MariaDB and Sendmail)

$ yum install gcc
$ yum install python
$ yum install java-1.8.0-openjdk-devel
$ yum install xorg-x11-fonts-75dpi zlib fontconfig freetype libX11 libXext libXrender urw-fonts

DBMS

Depending on the DBMS you want to use, either install MariaDB or MySQL.

MariaDB code repository for RedHat7:

$ subscription-manager repos –enable rhel-server-rhscl-7-rpms

MariaDB code repository for CentOS7:

yum install centos-release-scl

MariaDB DBMS

$ yum install rh-mariadb102-mariadb-server
$ yum install MySQL-python

Make sure MariaDB is running and re-started at every server reboot:

$ systemctl enable rh-mariadb102-mariadb
$ systemctl start rh-mariadb102-mariadb

MySQL DBMS

$ yum install rh-mysql57-mysql-server
$ yum install MySQL-python

Make sure MySQL is running and re-started at every server reboot:

$ systemctl enable rh-mysql57-mysql
$ systemctl start rh-mysql57-mysql

MTA

Depending on the MTA you want to use, either install Sendmail or Postfix.

MTA Sendmail

If you want to use Sendmail as SMTP server (MTA), you have to stop and remove Postfix first (in case it is installed), and you have to install the required packages for Sendmail.

# systemctl stop postfix
# yum remove postfix
# yum install sendmail sendmail-cf sendmail-milter procmail

After that, if necessary, switch the default SMTP server to Sendmail with

$ alternatives --set mta /usr/sbin/sendmail.sendmail

and change Sendmail's configuration: Open file sendmail.mc in directory /etc/mail and add a leading “dnl ” to line

DAEMON_OPTIONS(`Port=smtp,Addr=127.0.0.1, Name=MTA')dnl

This will enable Sendmail to listen on all available network interfaces and allows the processing of asynchronous bounces and auto responder mails. By default, Sendmail listens only on the local interface for connections, but dnl comments out this directive.
Additionally, add line

INPUT_MAIL_FILTER(`bav', `S=unix:/home/openemm/var/run/bav.sock, F=T')dnl

at the end of file sendmail.mc to make Sendmail familiar with OpenEMM's mail filter BAV (bounce address validator).
The mailloop of OpenEMM, which processes the asynchronous bounces and auto responder mails needs some more preparations:

$ cd /etc/mail
$ umask 022
$ [ -f relay-domains ] || touch relay-domains
$ [ -f mailertable ] || touch mailertable

To activate your changes to the Sendmail configuration you have to compile the intermediate file sendmail.mc to the final configuration file sendmail.cf and activate the new configuration with

$ cd /etc/mail
$ make
$ systemctl restart sendmail

MTA Postfix

If you want to use Postfix as SMTP server (MTA), you have to stop and remove Sendmail first (in case it is installed), and you have to install the required packages for Postfix.

$ systemctl stop sendmail
$ yum remove sendmail
$ yum install postfix sendmail-milter procmail

After that, switch the default SMTP server to Postfix with

$ alternatives --set mta /usr/sbin/sendmail.postfix

and change Postfix' configuration to unleash all features. To do this, change to the Postfix main configuration directory:

$ cd /etc/postfix

and add some configuration parameters to Postfix' main configuration file main.cf:

inet_interfaces = all
inet_protocols = all
mailbox_command = /usr/bin/procmail
mailbox_size_limit = 0
message_size_limit = 0
maximal_queue_lifetime = 1d
bounce_queue_lifetime = 1d
smtp_tls_security_level = may
smtp_tls_protocols = !SSLv2, !SSLv3
smtp_tls_ciphers = high
smtp_tls_mandatory_ciphers = $smtp_tls_ciphers
hash_queue_depth = 2
enable_long_queue_ids = yes
relay_domains = /home/openemm/var/run/relay.domains
transport_maps = hash:/home/openemm/var/run/transport.maps
smtpd_milters = unix:/home/openemm/var/run/bav.sock

If lines with parameters of the same name already exist in file main.cf, comment them with character # at the beginning to avoid any warning messages or overwrite them with the new values in case you do not want to keep the original values as backup.
Additionally, you have to set parameter myhostname in file main.cf to the FQDN of your OpenEMM server. Otherwise, mails would be sent with sender domain localhost.localdomain instead.
Finally, add these lines to configuration file master.cf:

mailloop unix - n n - - pipe
  flags=RX user=openemm argv=/usr/bin/procmail /home/openemm/lib/bav.rc

Please do not omit the two space characters before keyword “flags” to indicate the parser that the line is continued!
Last not least, activate the TLS manager in file master.cf by uncommenting (i.e. removing the leading #) line

tlsmgr unix - - n 1000? 1 tlsmgr

to permit sending of TLS encrypted emails.
To activate your changes, restart Postfix with

$ systemctl restart postfix

wkhtmltox

Download the RPM of “wkhtmltox” from wkhtmltopdf.org and unpack it:

$ rpm -ihv wkhtmltox-*.rpm

Firewall

Open port 25 and port 8080 in the firewall and add a port forwarding from port 80 to 8080:

$ firewall-cmd --get-active-zones

If your zone is “public” (if not, use the zone name you got with the aforementioned statement):

$ firewall-cmd -–zone=public –-add-port=8080/tcp –-permanent
$ firewall-cmd -–zone=public –-add-port=25/tcp –-permanent
$ firewall-cmd --zone=public --add-forward-port=port=80:proto=tcp:toport=8080 --permanent
$ firewall-cmd --reload

4. Installation

Group and User

Create group and user for OpenEMM:

$ groupadd openemm
$ useradd -m -g openemm -d /home/openemm -s /bin/bash openemm
$ passwd openemm
$ su - openemm

OpenEMM Download

Download the latest binary packages from here. The runtime package provides the installer for the backend and frontend code.

Runtime Deployment

Download runtime tarball (file name: openemm-gui-runtime-19.04.*.tar.gz) to /home/openemm to create the deployment and runtime environment for OpenEMM.

Change to user openemm, unpack and start it with

$ su - openemm
$ tar -xvzpf openemm-gui-runtime-19.04.*.tar.gz
$ ./OpenEMMInstaller.sh

At first launch the OpenEMMInstaller checks your environment and offers to install required packages and to set environment variables

  • JAVA_HOME (default: /usr/lib/jvm/java-8-openjdk-amd64) for Java
  • CATALINA_HOME (default: /home/openemm/tomcat/) for Tomcat
  • WKHTML (default: /usr/bin/wkhtmltoimage) for tool wkhtmltox

The parameters will be written to file setenv.sh in directory /home/openemm/bin/.

OpenEMMInstaller also checks if kernel parameter in /etc/security/limits.conf are sufficient and, if not, offers to change them. However, you have to restart OpenEMMInstaller as user root to be able to change the file:

$ sudo su -
$ /home/openemm/bin/OpenEMMInstaller.sh

If database configuration file dbcfg does not exist in directory /home/openemm/etc/, OpenEMMInstaller asks for the required parameters like database type (“mysql” or “mariadb”), database name (“openemm”), database user (“openemm”) and your database password.

Frontend and Backend Deployment

For the deployment of the backend tarball you have to run the OpenEMMInstaller as user root, because some files of the tarball have to be deployed with root permissions:

$ sudo su -
$ /home/openemm/bin/OpenEMMInstaller.sh

Use menu 4 or 5 to install the frontend and backend package. Menu 4 offers to install both, but you can select “n” for a package, if you do not want to install it.
During Deployment of the backend tarball several new directories and symlinks will be created in /home/openemm/.
If you do not want to install the backend package of OpenEMM, you can start den installer as user “openemm”:

$ su - openemm
$ OpenEMMInstaller.sh

5. Configuration

Log Access

OpenEMM requires read access to the mail log file at /var/log/maillog and logrotate has to be aware of this fact, too. Open file /etc/logrotate.d/syslog and add the following line after the line sharedscripts:

$ create 0644

and run

$ chmod 644 /var/log/maillog

to set the permissions of the current maillog.

OpenEMMInstaller

Use menu 2 and 3 of tool OpenEMMInstaller to change the configuration of OpenEMM.

Create an initial password for main user “emm-master” in menu “3 Security”.

Set various essential parameters in a sub-menu of menu “2 Configuration”:
emm.properties:

DB configuration:

  • Set rdir_domain to the protocol and FQDN of your OpenEMM server, for example https://openemm.example.com. This domain will be used in all measureable links to redirect them through OpenEMM.
  • Set mailloop_domain to the domain of your sender address. The domain for the mailloop must be different from the name of your OpenEMM server. It usually is the FQDN which is defined in the MX record for your server, for example mailing.example.com, pointing as MX to openemm.example.com. 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 the OpenEMM Install&Admin Guide.) If you do not configure the mailloop, OpenEMM can process only instant bounces (see “MTA” section above).

Launch OpenEMM with menu “7 Restart OpenEMM”.

Point your browser to your OpenEMM server and log in with user “emm-master” and the 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 help feature of OpenEMM, download tarball OpenEMM_Manual_*.tar.gz (not available, yet) from the AGNITAS website and use menu 5 to install as local file.

Templates and Forms

You do not have to start from scratch when producing mailings and creating forms in OpenEMM. At https://www.agnitas.de/en/download-center/ you can download templates and forms which you can import into OpenEMM. Make sure to replace all placeholders for a company ID with value “1”.

6. Updates

The 2nd line of this Wiki shows the latest available versions of OpenEMM runtime, backend and frontend. You can download the runtime version manually from here, copy it on your OpenEMM server and use menu 5 of the OpenEMMInstaller for deployment.
The latest backend and/or the frontend package of OpenEMM can be downloaded with menu 4 of the OpenEMMInstaller.

7. Administration

tbd

8. Known Issues

  • O-291: content for help menu is not available for download
  • O-333: it is not possible to revoke permissions of a user
  • O-336: workflow manager can not create new workflows

Fixed Issues

Runtime 19.04.079 or later:

  • O-272: sub-menu 3 of menu 2 in OpenEMMInstaller does not work

Frontend 19.04.000.268 or later:

  • O-328: validator prevents some mailings from being saved

9. Roadmap

tbd

start.txt · Last modified: 2019/05/24 14:46 by ma