Upgrade instructions

This document covers every changes an Ops needs to be aware of when running James.

The following procedures are to take as it, and the Apache Software Foundation, nor its contributors, can not be responsible for any damages generated by following the below procedures.

Before performing these operations, you should ensure to have the skills to conduct the operations, and you should read other software documentation. Do not follow this guide blindly!

3.3.0 version

Changes to apply between 3.2.0 and 3.3.0 will be reported here.

Change list:

Changes to the MailboxListener API

Persistent MailboxId for MailDir

Date: 30/11/2018

SHA-1: 7e32da51a29bee1c732b2b13708bb4b986140119

JIRA: https://issues.apache.org/jira/browse/MAILBOX-292

MailboxId are now persisted in a james-mailboxId file. This file is created on the fly, so no action is required for users relying on the MailDir mailbox.

Registration by MailboxId

Date: 30/11/2018

SHA-1: d9bcebc7dd546bd5f11f3d9b496491e7c9042fe2

JIRA: https://issues.apache.org/jira/browse/MAILBOX-354

Only user written components performing MailboxListener registration will be affected.

The MailboxPath is mutable and thus can be changed upon mailbox rename. This leads to significantly complex code with possible inconsistency windows.

Using the mailboxId, which is immutable, solves these issues.

Changes in WebAdmin reIndexing API

Date: 05/12/2018

SHA-1: 985b9a4a75bfa75c331cba6cbf835c043185dbdb

JIRA: https://issues.apache.org/jira/browse/JAMES-2555

We made this API introduced in James 3.2.0 a bit more REST friendly. If you developed tools using this API, you will need to update them.

For more details please refer to the latest WebAdmin documentation.


Date: 19/12/2018

SHA-1: e25967664538be18ec29f47e73e661bdf29da41f

JIRA: https://issues.apache.org/jira/projects/MAILBOX/issues/MAILBOX-356

Required: Yes

Concerned products: all JPA related products

Upgrade procedure

Rename KEY column in JAMES_MAILBOX_ANNOTATION table. The syntax is:

In MariaDB

or the syntax corresponding to your database.

Mailet API changes

In order to allow safe serialization and strong typing org.apache.mailet.Mail have changed.

These methods have been deprecated and replaced:

  • getSender() in favor of getMaybeSender()
  • getAttribute(String) in favor of getAttribute(AttributeName)
  • setAttribute(String, Serializable) in favor of setAttribute(Attribute)
  • removeAttribute(String) in favor of removeAttribute(AttributeName)
  • getAttributeNames() in favor of attributeNames() and attributesMap()

Some plain-string AttributeName have also been replaced:

  • SENT_BY_MAILET in favor of SENT_BY_MAILET_ATTRIBUTE's name, it is recommended to directly set the Attribute.

3.2.0 version

Changes to apply between 3.1.0 and 3.2.0 had been reported here.


Noticeable changes in Mail API: Mail::getMaybeSender

Date: 31/10/2018

SHA-1: 485406252d82c2d23a4078c76b26d6fc8973bbd7

JIRA: https://issues.apache.org/jira/browse/JAMES-2557

Required: Yes

Concerned products: User developed extensions - mailet/matcher

As part of the SMTP protocol, a mail can be sent without sender. This was represented implicitly in James by a potentially null MailAddress (null or MailAddress.nullSender()). This means that mailet/matcher implementers needs to be aware, and handle these cases. This implicit handling makes nullSender hard to work with, and prooved to be error prone as part of the 3.2.0 development process.

Hence we propose an alternative API returning a MaybeSender object, requiring the caller to explicitly handle missing sender.

Mail::getSender had then been deprecated. We strongly encourage our users to rely on Mail::getMaybeSender.

Note: thanks to java-8 default API methods, this is not a breaking change.

JMAPFiltering mailet is required for JMAP capable servers

Date: 30/08/2018

SHA-1: 9ba6a1dd270f99735c7f9d3d4b2adb5076583c10

JIRA: https://issues.apache.org/jira/browse/JAMES-2529

Required: Yes

Concerned products: Cassandra Guice products

This mailet allow users filtering rules to be applied for incoming emails.

Upgrade procedure

Add this line before the LocalDelivery mailet of your transport processor:

<mailet match="RecipientIsLocal" class="org.apache.james.jmap.mailet.filter.JMAPFiltering"/>

Cassandra 3.11.3 upgrade

Date: 03/08/2018

SHA-1: de0fa8a3df69f50cbc0684dfb1b911ad497856d7

JIRA: https://issues.apache.org/jira/browse/JAMES-2514

Required: Yes

Concerned products: Cassandra Guice products

James Cassandra Guice now officially uses Cassandra 3.11.3 as a storage backend. After performing the upgrade, the team did perform some breaking changes, detailed below. James Cassandra Guice products are no more tested against Cassandra 2.2.x. Thus we strongly advise our users to upgrade.

Changes not compatible with Cassandra 2.2.x

Replace in default compaction strategies “DateTieredCompactionStrategy” by “TimeWindowCompactionStrategy”.

This means you can no more start James on top of an empty Cassandra 2.2.x cluster, but existing deployments should not be impacted.

Upgrade procedure

We will assume that Cassandra had been installed with a debian package. Upgrade procedure stays similar in other cases.

  1. Update Cassandra dists in /etc/apt/sources.list.d/cassandra.list to match 311x repository
deb http://www.apache.org/dist/cassandra/debian 311x main
  1. Update Cassandra
$ apt-get update
$ apt-get install cassandra=3.11.3
  1. Correct the configuration

Edit /etc/cassandra/cassandra.yaml and ensure to really specify the interface cassandra is listening on as seeds.

  1. ReStart Cassandra

4.1. Drain data & stop

$ nodetool drain
$ nodetool stop

4.2. start Cassandra

  1. Upgrade SSTable (live update, performance degradation to expect)
$ nodetool upgradesstables apache_james