[2/3] james-project git commit: Add upgrade instructions

[ad...@apache.org]

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 <bt...@linagora.com>
Authored: Wed Aug 29 16:12:05 2018 +0700
Committer: Antoine Duprat <ad...@linagora.com>
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: server-dev-unsubscribe@james.apache.org
For additional commands, e-mail: server-dev-help@james.apache.org