1.4 Upgrade Instructions

From Enkive Wiki

(Redirected from Upgrade Instructions)
Jump to: navigation, search

Contents

Upgrading Enkive version 1.4 to 1.4.x

Note: Because of a still outstanding bug in 1.4.2 and 1.4.1, the path for the attachment document storage (i.e.: $ENKIVE_HOME/data/docstore/) in Enkive 1.4 must remain the same when upgrading to 1.4.2 or 1.4.1. You may want to wait for the 1.4.3 release. However, these upgrade instructions provide a fix around this.

Shutdown Enkive 1.4

/etc/init.d/enkive stop


Back up your data

Back up the MongoDB datastore.

You can use the mongodump utility. Please read the documentation at: http://docs.mongodb.org/manual/tutorial/backup-databases-with-binary-database-dumps/

The easiest way to back up MongoDB is to simply run the command:

mongodump

This assumes that MongoDB is currently running. That command will dump the database to the "dump/" directory in your current working directory.

By default the Enkive database in MongoDB is named "enkive", although it is a configurable option.

Next, back up the Indri index. By default, it is a directory located at $ENKIVE_HOME/data/indri/. For example:

cd /opt/enkive-1.4/data/
tar zcvf ~/indri-backup.tar.gz indri/


Unpack the Enkive 1.4.x tarball

Do not install Enkive 1.4.x over the Enkive 1.4 directory!

Instead of extracting the enkive 1.4.x tarball to a separate directory, you should first move the exiting $ENKIVE_HOME directory to another name, and remove any /opt/enkive symbolic link:

cd /opt/
[sudo] rm enkive
[sudo] mv enkive-1.4/ enkive-1.4.old

Now extract the new Enkive 1.4.x tarball:

 [sudo] tar zxvf enkive-1.4.2.tar.gz -C /opt/
 cd /opt/
 [sudo] mv enkive-1.4.2/ enkive-1.4
 [sudo] ln -s enkive-1.4/ enkive


Configure Enkive 1.4.x

Do not simply copy Enkive 1.4 configuration files over to the Enkive 1.4.x configuration files. The configuration options have changed and may break the install.

Instead, any changes you made to the 1.4 configuration files will have to be done by hand in an appropriate, analogous, and careful manner for 1.4.x. There are comments in the default configuration files to guide you.

All configuration will likely occur in the $ENKIVE_HOME/config/ directory. Primary configuration is in the enkive.properties file. There are default values for all settings in $ENKIVE_HOME/config/default/enkive.properties. Settings should be copied into /config/enkive.properties and modified to change them. Authentication is configured in $ENKIVE_HOME/config/resources/authentication/.

If you're not sure which configuration files have changed, you can extract the original Enkive 1.4 tarball to a temporary directory and make a diff with your current 1.4 install. For example, assuming our existing Enkive 1.4 is in /opt/enkive-1.4.old/:

tar zxvf enkive-1.4.tar.gz -C /tmp/
diff -r --brief /opt/enkive-1.4.old/config/ /tmp/enkive-1.4/config/

This "diff" command will show which files have been modified from the stock Enkive. Now you'll know what to customize in the Enkive 1.4.x config/ directory.


Copy the Indri index to the new location

By default the Indri index will be in each version of Enkive in $ENKIVE_HOME/data/indri/.

You can copy the existing Enkive 1.4 indri like so:

cp -a /opt/enkive-1.4.old/data/indri/

Or you can use the tarball backup of the Indri index we created earlier:

tar zxvf indri-backup.tar.gz -C /opt/enkive-1.4/data/


Create and configure the new 1.4.x initscript

Copy the new Enkive 1.4.x initscript over from /opt/enkive-1.4/scripts/init/generic/ into /etc/init.d/. If using Upstart with Ubuntu or Debian, copy the enkive.conf in /opt/enkive-1.4/scripts/init/ubuntu/ or /opt/enkive-1.4/scripts/init/debian/ to /etc/init/.

Modify the environment variables at the top of the new initscript.

Rename, move, or delete the old initscript


Re-make the Enkive Postfix filter

You need to create the Enkive socket filter again.

cd /opt/enkive-1.4/support/filters/postfix/enkive-socket-filter/
[sudo] make

Your "master.cf" file in your Postfix configuration should either point to /opt/enkive-1.4 or /opt/enkive (/opt/enkive being a symbolic link to /opt/enkive-1.4/).

Restart Postfix.


Copy or move the docstore directory

The attachment document store directory for the existing Enkive 1.4 is located at the old $ENKIVE_HOME/data/docstore/ location, or: /opt/enkive-1.4.old/data/docstore/.

Depending on the available space on your system, you may wish to move the docstore directory instead of copying it.

Copy the docstore directory to the new Enkive 1.4.x location:

 cd /opt/enkive-1.4.old/data/
 [sudo] cp -a docstore/ /opt/enkive-1.4/data/

This command will check that there is no difference between the copies (it may take a long time if you have a very large archive):

 [sudo] diff -r /opt/enkive-1.4/data/docstore/ /opt/enkive-1.4.old/data/docstore/


Adjust permissions

If you use a symbolic link /opt/enkive, make sure that it points to the new Enkive 1.4.x in /opt/enkive-1.4/.

If your Enkive runs as the "enkive" user, you will need to make sure that all the files and directories in the new Enkive 1.4.x directory are owned by the "enkive" user. For example:

chown -R enkive.enkive /opt/enkive-1.4/



Start Enkive 1.4.x

Start Enkive 1.4.x for the first time:

/etc/init.d/enkive start

or if using Upstart:

[sudo] service enkive start

Watch the logs for any messages that might indicate an error in the upgrade process.



Upgrading Enkive version 1.3.1 to 1.4.x


Shutdown Enkive 1.3.1

/etc/init.d/enkive stop


Back up your data

Back up the MongoDB datastore.

You can use the mongodump utility. Please read the documentation at: http://docs.mongodb.org/manual/tutorial/backup-databases-with-binary-database-dumps/

The easiest way to back up MongoDB is to simply run the command:

/opt/mongodb/bin/mongodump

This assumes your MongoDB is installed in /opt/mongodb/ and that MongoDB is currently running. That command will dump the database to the "dump/" directory in your current working directory.

By default the Enkive database in MongoDB is named "enkive", although it is a configurable option.

Next, back up the Indri index. By default, it is a directory located at $ENKIVE_HOME/data/indri/. For example:

cd /opt/enkive-1.3.1/data/
tar zcvf ~/indri-backup.tar.gz indri/


Install Enkive 1.4 in a separate directory

Do not install Enkive 1.4 over the Enkive 1.3 directory.

If your existing Enkive installation is at /opt/enkive-1.3.1/, you can install Enkive 1.4 with:

tar zxvf enkive-1.4.tar.gz -C /opt

which will put 1.4 into /opt/enkive-1.4/.


Configure Enkive 1.4

Do not simply copy Enkive 1.3.1 configuration files over to the Enkive 1.4 configuration files. The configuration options have changed and you will likely break the install.

Instead, any changes you made to the 1.3.1 configuration files will have to be done by hand in an appropriate, analogous, and careful manner for 1.4. There are comments in the default configuration files to guide you.

All configuration will likely occur in the $ENKIVE_HOME/config/ directory. Primary configuration is in the enkive.properties file. There are default values for all settings in $ENKIVE_HOME/config/default/enkive.properties. Settings should be copied into /config/enkive.properties and modified to change them. Authentication is configured in $ENKIVE_HOME/config/resources/authentication/.

If you're not sure which configuration files have changed, you can extract the original Enkive 1.3.1 tarball to a temporary directory and make a diff with your current 1.3 install. For example, assuming our existing Enkive 1.3.1 is in /opt/enkive-1.3.1/:

tar zxvf enkive-1.3.1.tar.gz -C /tmp/
diff -r --brief /opt/enkive-1.3.1/config/ /tmp/enkive-1.3.1/config/

This "diff" command will show which files have been modified from the stock Enkive. Now you'll know what to customize in the Enkive 1.4 config/ directory.


Copy the Indri index to the new location

By default the Indri index will be in each version of Enkive in $ENKIVE_HOME/data/indri/.

You can copy the existing Enkive 1.3.1 indri like so:

cp -a /opt/enkive-1.3.1/data/indri/

Or you can use the tarball backup of the Indri index we created earlier:

tar zxvf indri-backup.tar.gz -C /opt/enkive-1.4/data/


Create and configure the new 1.4 initscript

Copy the new Enkive 1.4 initscript over from /opt/enkive-1.4/scripts/enkive into /etc/init.d/. If using Upstart with Ubuntu or Debian, copy the enkive.conf to /etc/init/.

Modify the environment variables at the top of the new initscript.

Rename, move, or delete the old initscript


Adjust permissions

If you use a symbolic link /opt/enkive that points to your existing Enkive 1.3.1, you'll need to change it to point to the new Enkive 1.4.

If your Enkive runs as the "enkive" user, you will need to make sure that all the files and directories in the new Enkive 1.4 directory are owned by the "enkive" user. For example:

chown -R enkive.enkive /opt/enkive-1.4/


Re-make the Enkive Postfix filter

You need to create the Enkive socket filter again.

cd /opt/enkive-1.4/support/filters/postfix/enkive-socket-filter/
[sudo] make

Your "master.cf" file in your Postfix configuration should either point to /opt/enkive-1.4 or /opt/enkive (/opt/enkive being a symbolic link to /opt/enkive-1.4/).

Restart Postfix.


Migrate the MongoDB database

If you were to try to start Enkive now, you would likely get an error message that you need to migrate your database.

Starting with Enkive release 1.4, email attachments are now stored in the filesystem at $ENKIVE_HOME/data/docstore/ instead of inside the MongoDB database.

First, edit the environment variables in $ENKIVE_HOME/scripts/enkive-common.sh.

Run the migration script:

sh /opt/enkive-1.4/scripts/enkive-migration-tool.sh

Depending on the size of your archive, this could take a long time...

The output from a successful run of the migration script should look like this:

[root@enkive scripts]# sh enkive-migration-tool.sh
Note: you may need to authenticate as user "root"....
The database appears to need migrations. It is important to create a backup of the database before running migrations.
Do you confirm that you have created a full backup of the database (YES/no)? YES
The migrations have now completed. Checking database status again....
The database now appears to be up to date.


Create new MongoDB Indices

If you were to try to start Enkive now, you would likely get a warning message about missing indices. While it is not strictly necessary to rebuild these, it will cause a significant slowdown to searching, especially if the IMAP connector is used. To build the new indices, run the index creation script:

sh /opt/enkive-1.4/scripts/mongodb-index-tool.sh

Note that this may take a while, if you have a large database of stored email and searches. This may be run at any time, so it may be postponed until downtime can be scheduled.


Start Enkive 1.4

Start Enkive 1.4 for the first time:

/etc/init.d/enkive start

Watch the logs for any messages that might indicate an error in the upgrade process.


Personal tools