Building and Configuring Apache James with OpenLDAP

[ This post is part of my ongoing instructional series on setting up some baseline IT infrastructure for the fictional startup Shoestring Lab. Shoestring has committed to using Open Source wherever possible. Shoestring Lab has standardized on Ubuntu for its server and desktop/laptop computer systems.

Today's lesson

Now that you have built a central user repository for your network using OpenLDAP, you need to configure an email server to use the OpenLDAP user repository.]

Apache James is a modern modular email server system that runs on the JVM. The James project has seen many significant updates in recent years, including the use of Apache Cassandra as a data store and Elasticsearch as a search system. James now has several alternate configurations that can be easily built from its source tress. One of the optional configurations uses OpenLDAP as a read-only user repository for email account provisioning. By using OpenLDAP as the user repository, we can leverage the investment in the mature and scalable OpenLDAP project and help to centralize user provisioning in our network infrastructure.

As of this writing, the James email server successfully builds the LDAP-based target from the Git repo at commit eb15e9a74b5338bda80617e6c788bcb707e67e08. Following are instructions for building the project from source on Ubuntu 19.04.

  1. Clone the James repository, which is now located at GitHub:

    $ git clone
  2. Build the Cassandra-LDAP-Guice target project. You will need to have maven installed on your system to build the packages.

    $ mvn package -DskipTests --also-make --projects server/container/guice/cassandra-ldap-guice
  3. Build the server CLI target project:

    $ mvn package -DskipTests -am -pl server/container/cli
  4. Copy jars and libs from ./server/container/guice/cassandra-ldap-guice/target to a working folder for testing.
  5. Configure the XML and properties files in the /conf folder for James. Because proper setup on the configuration files is so involved, for the purpose of this tutorial, I have included an archive containing a set of files with the configuration already completed for testing purposes. Download the archive below and unzip the /conf folder and its contents into the working folder you created. These files configure the server to send and receive mail for the domain using the OpenLDAP server we previously configured.
  6. Install Apache Cassandra. For this project, I have installed Cassandra using apt @ v 3.11.4. 
  7. Install ElasticSearch. I have installed ElasticSearch OSS 6.5.0 using the .deb package.
  8. Configure OpenLDAP. For the purposes of this tutorial, I am accessing the OpenLDAP server at: ldap://localhost:389 using administrator password shoelaces, which is configured in conf/usersrepository.xml. If you are folllowing the rest of the series on setting up OpenLDAP, the password is the same administrator password you created when you installed OpenLDAP.
  9. Following the previous tutorials for adding groups to OpenLDAP and adding people to groups, create a group in the OpenLDAP store for email users. The DN for the group should be:

  10. Start the James server for testing:

    $ sudo java -jar ./james-server-cassandra-ldap-guice.jar

    Note that James requires a Java JDK 8 JVM. Set your JAVA_HOME environment variable to point to your JDK home. For the purposes of this tutorial, I am using the latest version of OpenJDK 8.
  11. Use telnet to check IMAP and SMTP services of the James server. To test access, use the credentials for an OpenLDAP account you created previously in the tutorial on adding users to OpenLDAP. Note that you should use only the user name, not the full email address, for the username.
  12. Configure a local email client with an account to access the James mail server.

Important! This is not a full production configuration for the James email server. To properly get James configured to serve mail in the context of modern email services, you will need to configure a few other things to enable validation of your email server. I will be covering those items in future tutorials.