Add upgrade instructions
Project: http://git-wip-us.apache.org/repos/asf/james-project/repo Commit: http://git-wip-us.apache.org/repos/asf/james-project/commit/d2a590fb Tree: http://git-wip-us.apache.org/repos/asf/james-project/tree/d2a590fb Diff: http://git-wip-us.apache.org/repos/asf/james-project/diff/d2a590fb Branch: refs/heads/master Commit: d2a590fb1a95d48735dd8a0c27a7847f3c79fc14 Parents: 554d50a Author: Benoit Tellier <[email protected]> Authored: Wed Aug 29 16:12:05 2018 +0700 Committer: Antoine Duprat <[email protected]> Committed: Thu Aug 30 15:30:44 2018 +0200 ---------------------------------------------------------------------- upgrade-instructions.md | 105 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 105 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/james-project/blob/d2a590fb/upgrade-instructions.md ---------------------------------------------------------------------- diff --git a/upgrade-instructions.md b/upgrade-instructions.md new file mode 100644 index 0000000..7c52848 --- /dev/null +++ b/upgrade-instructions.md @@ -0,0 +1,105 @@ +# 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! + +## Unreleased + +Note: this section is in progress. It will be updated during all the development process until the release. + +Changes to apply between 3.1.x and 3.2.x will be reported here. + +Changelist: + + - [JMAPFiltering mailet is required for JMAP capable servers](#jmapfiltering-mailet-is-required-for-jmap-capable-servers) + - [Cassandra 3.11.3 upgrade](#cassandra-3113-upgrade) + +### JMAPFiltering mailet is required for JMAP capable servers + +Date: XXXX + +SHA-1: XXXX + +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 +``` + + +2. Update Cassandra + +``` +$ apt-get update +$ apt-get install cassandra=3.11.3 +``` + +3. Correct the configuration + +Edit /etc/cassandra/cassandra.yaml and ensure to really specify the interface cassandra is listening on as seeds. + +4. ReStart Cassandra + +4.1. Drain data & stop + +``` +$ nodetool drain +$ nodetool stop +``` + +4.2. start Cassandra + +5. Upgrade SSTable (live update, performance degradation to expect) + +``` +$ nodetool upgradesstables apache_james +``` + --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
