4 Installing Enterprise Data Quality with Apache Tomcat

These are the steps required to install and configure Enterprise Data Quality with Apache Tomcat.

Prerequisites

Before you begin the installation, review the following prerequisites:

  • Oracle Database versions 19c and later are supported
  • Tomcat versions 9.0.x and later are supported
  • Java versions 17 or 21 are required

Creating Oracle Database Schemas

Create Oracle users for the EDQ configuration and results schemas. For both schemas, grant the following privileges:

GRANT UNLIMITED TABLESPACE TO user;
GRANT CREATE ANY VIEW TO user;
GRANT "CONNECT" TO user;
GRANT "RESOURCE" TO user;

For the configuration schema, the following additional privileges are required:

GRANT CTXAPP TO user;
GRANT CREATE ANY JOB TO user;

Note:

This does not apply if you are using a Derby database.

Installing Tomcat and Java

Tomcat versions 9.0.x and later are supported. Details of the install mechanism and Tomcat startup are operating system dependent and cannot be covered in detail here.

In Linux systems using systemd, the following is an example of a unit file which can be used to start Tomcat automatically at system boot:

Tomcat systemd unit file

[Unit]
Description=Apache Tomcat - instance %i
After=syslog.target network.target
 
[Service]
Type=forking
 
User=tomcat
Group=tomcat
 
WorkingDirectory=/var/tomcat/%i
 
Environment="JAVA_OPTS=-Djava.security.egd=file:///dev/urandom"
 
Environment="CATALINA_PID=/var/tomcat/%i/run/tomcat.pid"
Environment="CATALINA_BASE=/var/tomcat/%i/"
Environment="CATALINA_HOME=/opt/tomcat/"
Environment="CATALINA_OPTS=-Xmx8192M"
 
ExecStart=/opt/tomcat/bin/startup.sh
ExecStop=/opt/tomcat/bin/shutdown.sh
 
[Install]
WantedBy=multi-user.target

In this example, the Tomcat home location is /opt/tomcat and the Tomcat base location is/var/tomcat/INSTANCE. For example, to start an instance named edq, you can use the following command:

sudo systemd start tomcat@edq.service

Note:

EDQ 14.1.2.0.0 requires Java versions 17 or 21, so ensure that the new Tomcat install is configured to either of these versions.

Installing Enterprise Data Quality

Run the installer and select the Installation for Other Platforms option. For more information on EDQ installation, see Installing Enterprise Data Quality.

Initializing the EDQ schemas and creating the configuration directories

The EDQ home and local configuration areas must be created and the schemas initialized before proceeding. There are two approaches - a graphical configuration tool for Oracle or a manual setup.

Using the graphical configuration tool

If you are using an Oracle database, the configuration can be performed using the configapp.jar tool shipped with EDQ:

$ java -jar configapp.jar

To initialize the EDQ schemas and create the configuration directories, follow these steps:

  1. Enter the location for the home and local configuration directories.

  2. Select the required functional packs. By default, all are selected.

  3. Enter the connection details for the configuration schema.

  4. Enter the connection details for the results schema.

  5. Click Finish on the summary screen to proceed.

Schema configuration is specified with the user name and password and the database connection details. On completion, the EDQ schema are initialized and the configuration directories are created.

Manual setup

If you are using a Derby database, or cannot readily run a graphical tool, the setup can be performed manually. The following steps are required for a manual setup:

1. Create configuration directories

Run the configapp.jar in 'extract mode' to create the home and local configuration directories:

$ java -jar configapp.jar extract -home homedir -local localdir

2. Initialize the EDQ configuration schema

Use the migration.jar tool to initialize the configuration schema:

For Oracle use:

$ java -jar migration.jar init oracle:#SERVICE@HOST:PORT/USER/PASSWORD

Replace SERVICE, HOST, PORT, USER and PASSWORD with the correct values for your Oracle schemas.

For Derby use:

$ java -jar migration.jar init 'derby:(/path/to/db;create=true)'

Where /path/to/db refers to a non-existent directory which will be created and populated with the database files.

3. Edit director.properties

The local configuration directory is created with a template director.properties which must be edited to specify the database connection details. The initial contents are:

Template director.properties

# local home director.properties
 
# Configuration schema setup for Oracle
# -------------------------------------
 
#dataSource.driverClassName        = oracle.jdbc.OracleDriver
#dataSource.url                    = jdbc:oracle:thin:@hostname:1521/service
#dataSource.username               = user
#dataSource.password               = password
 
# Results schema setup for Oracle
# -------------------------------
 
#resultsDataSource.driverClassName = oracle.jdbc.OracleDriver
#resultsDataSource.url             = jdbc:oracle:thin:@hostname:1521/service
#resultsDataSource.username        = user
#resultsDataSource.password        = password
 
# Configuration schema setup for Derby
# ------------------------------------
 
#dataSource.driverClassName        = org.apache.derby.jdbc.EmbeddedDriver
#dataSource.url                    = jdbc:derby:directory
#dataSource.username               = APP
#dataSource.password               = app
 
# Results schema setup for Derby
# ------------------------------
 
#resultsDataSource.driverClassName = org.apache.derby.jdbc.EmbeddedDriver
#resultsDataSource.url             = jdbc:derby:directory
#resultsDataSource.username        = APP
#resultsDataSource.password        = app

If you are using Oracle, uncomment the first two blocks and set the correct values for the database host, port, service name and credentials. For example:

Example Oracle configuration

# local home director.properties
 
# Configuration schema setup for Oracle
# -------------------------------------
 
dataSource.driverClassName        = oracle.jdbc.OracleDriver
dataSource.url                    = jdbc:oracle:thin:@dbhost:1521/pdb1
dataSource.username               = edq_config
dataSource.password               = passwd1
 
# Results schema setup for Oracle
# -------------------------------
 
resultsDataSource.driverClassName = oracle.jdbc.OracleDriver
resultsDataSource.url             = jdbc:oracle:thin:@dbhost:1521/pdb1
resultsDataSource.username        = edq_results
resultsDataSource.password        = passwd2

If you are using Derby, uncomment the second two blocks and replace directory with the path to the Derby database created in the initialization step above.

EDQ on Derby

Deploying EDQ war file

EDQ 12.2.1.4.3 and later on Tomcat support the use of an embedded Apache Derby database for the configuration and results schemas.

Creating the database

The migration.jar tool shipped with EDQ can be used to create and initialize a Derby database: 

 java -jar migration.jar init 'derby:(/path/to/db;create=true)'

The path should refer to a non-existent directory which is where the database files will be created. After creation the files can be copied for use with EDQ.

Configuring EDQ

Use these properties to configure EDQ to use the Derby database:

dataSource.driverClassName        = org.apache.derby.jdbc.EmbeddedDriver
dataSource.url                            = jdbc:derby:/dbpath
dataSource.username                       = APP
dataSource.password                       = app

resultsDataSource.driverClassName         = org.apache.derby.jdbc.EmbeddedDriver
resultsDataSource.url                     = jdbc:derby:/dbpath
resultsDataSource.username                = APP
resultsDataSource.password                = app

/dbpath is the absolute location of the directory containing the database files created in the first step.

Use with OCI

The setup process for the 12.2.1.4.3 and later Tomcat Marketplace images has been updated to include Derby as a schema configuration option. If selected, no further configuration is required.

In-memory databases

EDQ versions after 14.1.2.0.0 support in-memory Derby databases. This can be useful for throwaway instances running in environments like Kubernetes or OKE.

Use these properties to configure EDQ to use an in-memory database:

dataSource.driverClassName        = org.apache.derby.jdbc.EmbeddedDriver
dataSource.url                    = jdbc:derby:memory:db1
dataSource.username               = APP
dataSource.password               = app

resultsDataSource.driverClassName = org.apache.derby.jdbc.EmbeddedDriver
resultsDataSource.url             = jdbc:derby:memory:db1
resultsDataSource.username        = APP
resultsDataSource.password        = app

At startup EDQ will detect an in-memory database and initialize the configuration schema automatically.

The initial administration user will be created with the "change password at login" option enabled, as in a normal setup. To allow the instance to be used immediately for API calls, some SQL can be executed on the configuration database at startup to remove this option. Add this property:

dataSource.init.sql = UPDATE dn_user SET psswdexp_policy = NULL

The init.sql property can contain multiple SQL statements, separated by newline (\n) characters.

Encrypted databases

Derby databases are stored in the file system and are not encrypted by default. If a database contains sensitive information, it can be encrypted using standard Java ciphers. To initialize an encrypted database, use a command like:

java -jar migration.jar init 'derby:(/path/to/db;create=true;dataEncryption=true;bootPassword=mysecretpassword;encryptionAlgorithm=AES/CBC/NoPadding;encryptionKeyLength=256)'
Subsequently the bootPassword property must be specified when the database is opened. This could be done by adding the property to the database URL in director.properties but it is insecure to specify passwords in plain text. It should be possible to store the password in any of the credentials providers configured in the instance. This can done by defining boot password initialization properties. For example, to retrieve the password from an OCI or AWS credentials store, use:
dataSource.init.bootPassword.cred.secret                  = mybootsecret
dataSource.init.bootPassword.cred.secret.passwordonly     = true

The cred.secret property specifies the secret name in the store and the cred.secret.passwordonly specifies that the secret value is a single string rather than a username and password pair.

Copy the EDQ war file to the Tomcat webapps directory. For Tomcat version 9.0.x, use edq.war. For Tomcat versions 10.1.x and later, use jakartaee/edq.war.

Configuring Tomcat to use the Configuration Directories

Once the configuration directories are created and the schema initialized, Tomcat must be configured to use the directory path. This is done by setting the EDQ_CONFIG_PATH environment variable to the path. The environment variable can be set globally, or in the Tomcat start scripts or in the systemd unit file as above, or by creating a setenv.sh script in the Tomcat bin directory. For example:

Example setenv.sh file setting environment variable

EDQ_CONFIG_PATH=/opt/edq/oedq.home:/opt/edq/oedq.local.home
export EDQ_CONFIG_PATH

The value should be the home and local directory locations, separated by a colon. On Windows, the script file is setenv.bat and the path separator is a semicolon.

Alternatively, the path can be set using the edq.config.path system property. This can also be set in setenv.sh:

CATALINA_OPTS="-Dedq.config.path=/opt/edq/oedq.home:/opt/edq/oedq.local.home"

Installing EDQ launcher application

EDQ 14.1.2.0.0 does not use Java WebStart to launch the client applications. A new EDQ launcher application must be installed on client systems. This application can be downloaded from the link at the bottom right of the EDQ launchpad. Versions for Windows, Mac, Intel Linux .rpm and Intel Linux .deb are available.

Versions of the launcher shipped with EDQ 12.2.1.4.x are supported, but it is recommended to update to the version shipped with 14.1.2.0.0.