CloverDX Server installation on RHEL and CentOS

Starting CloverDX 5.16.0, server installer is available via an RPM package making it easy to install and maintain going forward using YUM or DNF package managers.
Generally, any installation can be broken down to several steps:

  1. Configuration of repositories
  2. Package installation
  3. Database configuration
  4. Hardening of deployment

Last two are optional for evaluation purposes but closer the deployment gets to production setup, more important they become. Even for more complex test scenarios or collaborative development will require backend database to be properly configured at the very least.

In this article, let’s focus on an installation of development environment in its most basic form with relaxed security settings as hardening of an installation is rather extensive topic and would easily span over several blog posts.

On a high-level, hardening would encompass setting up HTTPS for both Server and Worker, setting up user permissions, SSO/LDAP authentication etc. Let me know in comments if that’s a topic you’d be interested in.

There are mainly two reasons for not using embedded (Apache Derby) database. First, strictly from engineering standpoint:

  • its performance is sub-optimal when database size grows in size
  • deployment in cluster setup is practically impossible
  • is being known for causing issues during software updates (data loss)
and secondly, it is unsupported configuration outside of software evaluation.

Setting up CloverDX RPM repository

Depending on the installation strategy, you will need to add 2 to 3 new repositories to be added to your package manager. One for CloverDX, second for Java (Eclipse Temurin) and optionally third for database engine. In this article, we’re going to use PostgreSQL but it is possible to use any of supported ones either pre-installed or use different repository to install it.

$ sudo curl -o /etc/yum.repos.d/cloverdx.repo https://packages.cloverdx.com/rpm/centos/7/cloverdx.repo

Running this command will make repository registered with your package manager. Adding one for Eclipse Temurin is now only a matter of installing a package from CloverDX repository.

$ sudo yum install -y adoptopenjdk-repo

Alternatively, same result may be achieved following instructions on adoptopenjdk blog how to add AdoptOpenJDK repository for RPM files. 

Since we’re going to use latest supported PostgreSQL database, we’re also going to install official PostgreSQL repository as database packages in official CentOS / RHEL ones are painfully outdated.

$ sudo yum install -y https://download.postgresql.org/pub/repos/yum/reporpms/EL-7-x86_64/pgdg-redhat-repo-latest.noarch.rpm

Package installation

At this point, simply running sudo yum install -y cloverdx would be enough to install CloverDX for evaluation purposes. But since the goal here is to set up more robust deployment; running sudo yum install -y cloverdx postgresql14-server is more desirable.

At this point, it is possible to start CloverDX Server to test out successful installation with sudo systemctl start cloverdx. Still, it is necessary to configure database; running sudo systemctl stop cloverdx will terminate running instance.

A little specific to PostgreSQL, it is necessary to initialize database, sudo /usr/bin/postgresql-14-setup initdb before it can be started.

Database configuration

Generally the most time consuming task when running any enterprise application. Thanks to YUM/RPM though, this can be boiled down only to database creation and configuring CloverDX Server connection. For most databases, even better; this can be accomplished directly from CLI and therefore fully automated for headless installation.

Prepare database

Since database is already installed and initialized (see previous chapter), now it is time to start it (sudo systemctl start postgresql-14) and create new database with dedicated user for CloverDX Server:

$ sudo -u postgres sh –c \
    "psql -c \"CREATE USER cloverdb WITH PASSWORD 'cloverdb'\" && \
     psql -c \"CREATE DATABASE cloverdb WITH OWNER cloverdb\""

Configure CloverDX database connection

CloverDX Server uses properties file to provide configuration for various capabilities, like to set up clustering or use SSO/LDAP server. It also serves as configuration provider for backend database where runtime information is being stored. Like for example schedules, execution history, permission control etc.

There are 2 ways, one can set up this connection.

  1. Directly, via JDBC
  2. Using JNDI connection pool

Former has the advantage of being trivial to set up. Just provide connection details to /etc/cloverdx/clover.properties and server is ready to be started. Drawback being, connections will not for example, be health-checked. There is also some performance gain as connections managed by pools are kept alive during entire runtime, therefore overhead caused by initial handshake will not impact downstream applications (i.e., CloverDX Server). For more robust deployments it is always recommended to connect via pooled JNDI provided by an application server. In our case, implementation of JDBC pool is Apache DBCP 2, an integral part of Apache Tomcat.

Common step for both approaches is to download necessary database driver into Apache Tomcat lib directory, located /var/lib/cloverdx/lib.

$ sudo curl -o /var/lib/cloverdx/lib/postgresql-42.5.0.jar \
	https://jdbc.postgresql.org/download/postgresql-42.5.0.jar

Optionally, you may also disable Apache Derby by exclusion of config file from server initialization sequence.

$ sudo mv /etc/cloverdx/conf.d/99_derby.sh /etc/cloverdx/conf.d/99_derby.sh.disabled

This will effectively disable Apache Derby altogether as it will fail to store its data into root / of your filesystem to which it will not have permissions. It is optional because if database is properly configured, attempt to run Apache Derby database will not be made in the first place.

Option 1: Configuration via direct JDBC connection

Find appropriate template already present in /etc/cloverdx/clover.properties, uncomment set of properties pre-set for PostgreSQL and of course, set configuration properties appropriately.

OR

Run following script (changing properties appropriately):

$ cat <<'EOF' | sudo tee --append /etc/cloverdx/clover.properties >/dev/null
jdbc.driverClassName=org.postgresql.Driver
jdbc.url=jdbc:postgresql://localhost:5432/cloverdb?charSet=UTF-8
jdbc.username=cloverdb
jdbc.password=cloverdb
jdbc.dialect=org.hibernate.dialect.PostgreSQLDialect
EOF

Option 2: Configuration via JNDI 

This is a 2-step task; first it is necessary to configure JNDI itself and in second step configure CloverDX Server to use it. It is not difficult but not something very straightforward to do if you don’t know what JNDI is and how it works.

In short, JNDI creates an alias for remote resource and proxies connectivity between an application (CloverDX Server) and the resource (PostgreSQL) making configuration more portable between environments. In our situation, it also adds benefits of connection pooling.

JNDI in Apache Tomcat can be set up in multiple places, for different scopes (per application, global). In case such as ours (for scope of single application), it tends to be best to put in context configuration file – /etc/cloverdx/Catalina/localhost/clover.xml. Keeping existing <Context> tag, adding <Resource> (database connection settings), result may look similar to:

<Context path="/clover" docBase="/usr/share/cloverdx/clover.war">
  <Resource name="jdbc/cloverdb"
     auth="Container"
     type="javax.sql.DataSource"
     factory="org.apache.tomcat.jdbc.pool.DataSourceFactory"
     driverClassName="org.postgresql.Driver"
     url="jdbc:postgresql://127.0.0.1:5432/cloverdb"
     username="cloverdb"
     password="cloverdb"
     maxTotal="20"
     maxIdle="10"
     maxWaitMillis="-1"/>
</Context>

For complete set of configuration options and their description, refer to Apache DBCP documentation.

Having JNDI configured, copy <Resource name="[ value ]"> and open /etc/cloverdx/clover.properties. There should already be a template for JNDI setup, just uncomment it and change datasource.jndiName to [ value ], adding prefix java:comp/env/; result should look something like java:comp/env/jdbc/cloverdb. Or simply run (changing jndiName appropriately):

$ cat <<'EOF' | sudo tee --append /etc/cloverdx/clover.properties >/dev/null
datasource.type=JNDI
datasource.jndiName=java:comp/env/jdbc/cloverdb
jdbc.dialect=org.hibernate.dialect.PostgreSQLDialect
EOF

First start

Before starting server, you might want to place license into /etc/cloverdx/license.dat even though it may not be necessary – you will be prompted to put license in, when server boots up.

$ sudo systemctl start cloverdx

To access server console, open http://localhost:8083/clover.

Depending on your server’s configuration (e.g., Amazon Linux does not require this but other distros usually do); you might need to open port 8083 (or change it in /etc/cloverdx/server.xml) with sudo firewall-cmd --add-port=8083/tcp.

To stop server, run:

$ sudo systemctl stop cloverdx

Conclusion

Now, we should have a CloverDX Server set up in a configuration which should be ready for internal development purposes on local networks. In case, we’d like to promote to production or UAT environments or anywhere else live data may be expected we also need to think about security.

Security is a large concern these days and would require more than one article to do more than just scratch the surface. In our world, security relates to transfer and storage security (technical aspect), user access provisioning (user perspective) and configuration protection (secrets used by server backend) provided in plaintext (/etc/cloverdx/clover.properties or /etc/cloverdx/Catalina/localhost/clover.xml) for purposes if this article.

About security, perhaps next time.

More from Tech Blog

Visit CloverDX Blog

Read On