Apache James Self Hosting Sandbox

James does not work "out-of-the box". You have a bit of work to do to make it run. To operate a James server, you must first configure and build it.

This repository provides an environment for allowing you to configure and build your own James server.

Related issues:

• https://issues.apache.org/jira/browse/JAMES-3209

See DETAILS.adoc for additional technical details about this project.

James Servers

You have two choices of James Servers to choose from:

1. James Basic Server - use this if you are not familiar with James

2. James Custom Server - use this if you know what you are doing

How to build a Basic Server

(TODO)

How to build a Custom Server

Configure the Server

Choose from the template files in the ./conf directory for those components that you wish to configure differently from the default configuration and copy to ./james-custom-server/conf.

Build the base James Distribution

Build a base James distribution and base the Custom Server on this distribution:

    # Run the build from the top directory of the project
    cd $PROJECT_DIR
    # Note: you can use --refresh-dependencies to force SNAPSHOT updates
    ./gradlew clean build
    # Look under build/distributions/ for results.

Build and Run the Custom Server with docker-compose

The recommended way is to run the Custom Server is with docker-compose. The docker-compose configuration will build the james-server image for you so you do not need to run docker build.

    # Build james-server-and-cli image and start the services
    # Note: use --build to force build the docker image
    docker-compose up --build -d
    # See the logs
    docker-compose logs -f

You can save a few steps this way:

    docker-compose up --build -d && docker-compose logs -f

When you are done playing, remove all containers and data volumes:

    docker-compose down -v

Debugging

If you need to debug the code, follow these instructions.

Setting up your IDE

(TODO)

Run James with gradle

Instead of running via docker-compose, use gradle, which will …​ (TODO)

    ./gradlew :james-server:run

Plain Docker

For completenes we will show how to also build the image with plain docker.

    # Build the distributions
    ./gradlew clean build
    # Build the docker image from the top directory
    docker build -t james-server-and-cli -f james-custom-server/Dockerfile .

Modules

The modules are meant to be kept independent. They share the git repository. They are aggregated via docker only.

james-server

This module builds the email server application

james-cli

This module builds the command line utility for using it with a server

james-extensions

This module contains sample code on how to extend James server

James server

This module builds the email server. It depends on the james-extensions gradle module so it will include all the customizations from there. It uses gradle application plugin to package all java libraries into a lib directory. The application plugin also provides nice linux and windows startup scripts that we can customize.

You can run james server locally via gradle (curtosy of application plugin)

    # Run the server with
    ./gradlew clean build :james-server:runJamesServer

James Extensions

This module should contain code samples on how to extend Apache James.

We are talking about: * a simple NoOP mailet * a SMTP hook * Mailbox Listener

The extensions module is built as a library and included in the final james-server application.

Mailets and matchers

Samples for mailets and matchers are in ro.ieugen.sample.mailets package.

The steps are as follows:

• Implement a matcher and/or a mailet class

• Add them to the classpath of james-server

• Configure them in mailetcontainer.xml

ro.ieugen.sample.mailets.LogAndDoNothingMailet.java

@Slf4j
public class LogAndDoNothingMailet extends GenericMailet {

  @Override
  public void init() throws MessagingException {
    log.info("initialize mailet");
  }

  @Override
  public void service(Mail mail) throws MessagingException {
    log.info("Service the email {}", mail.getName());
  }
}

ro.ieugen.sample.mailets.MatcherMadeInHeaven.java

@Slf4j
public class MatcherMadeInHeaven extends GenericMatcher {

  @Override
  public void init() throws MessagingException {
    log.info("Build Heaven. Initialize matcher");
  }

  @Override
  public Collection<MailAddress> match(Mail mail) throws MessagingException {
    log.info("Matching for heaven {}", mail.getName());
    return Collections.emptyList();
  }
}

mailetcontainer.xml

    <processor state="do-nothing-mailet" enableJmx="false">
      <mailet match="All" class="ro.ieugen.sample.mailets.LogAndDoNothingMailet"/>

      <mailet match="ro.ieugen.sample.mailets.MatcherMadeInHeaven"
        class="ro.ieugen.sample.mailets.LogAndDoNothingMailet"/>
    </processor>

James CLI

This module provides the CLI for James server administration. It is also built with the gradle application plugin and provides a bash script for calling it.

James CLI uses a JMX over HTTP connection to operate so it will need access to the administration port.