Driven Administrator Guide

version 1.2

Migrating Your Data for a Driven Upgrade

Tip	Contact Technical Support before starting migration.

Prerequisites

Ensure that all applications that feed data to Driven do not run while performing upgrade and migration.
Back up the data of your Driven deployment. See Backing Up and Restoring Driven Repositories for more information.
For sites running a stand-alone Elasticsearch cluster: Upgrade the cluster to Elasticsearch version 1.4.3. Also, if required, upgrade Elasticsearch plugins to be compatible with version 1.4.3.

Task Overview

Data migration from the last major Driven Server version to Driven Server 1.2 requires that you perform the following tasks in sequential order:

Upgrade the Driven Server by replacing the WAR file
Install the latest version of the CLI Client
Perform the migration process
Verify migration and reindexing status

Upgrade the Driven Server and CLI Client

To upgrade the Driven Server, you need to replace the WAR file contents of your deployment with the contents of the version 1.2 WAR file while the server is stopped. After you restart the server, install the version 1.2 Driven CLI Client.

Note	After you replace the WAR file, you cannot log in to Driven until you complete the migration process.

Step 1: Download the Driven Server installation ZIP archive, which includes Apache Tomcat and embedded Elasticsearch libraries, by one of the following methods:

Download the ZIP archive from http://files.concurrentinc.com/driven/1.2/driven-server/driven-tomcat-1.2.zip
Alternatively, on UNIX, Linux, and Mac, run the following command:

$ wget -i http://files.concurrentinc.com/driven/1.2/driven-server/latest-tomcat.txt

Step 2: Extract the ZIP archive to the default driven-tomcat-1.2/ directory, which is later referred to as ${UPGRADE_DIR}.

Step 3: Run the shutdown.sh script in the Driven installation directory:

$ cd ${INSTALL_DIR}
$ bin/shutdown.sh

Step 4: Remove the contents of the ${INSTALL_DIR}/webapps/ directory by running the following command:

$ rm -rf ${INSTALL_DIR}/webapps/*

Step 5: Copy the WAR file from the newly extracted webapps directory to the webapps directory in the Driven installation path:

$ cp ${UPGRADE_DIR}/webapps/ROOT.war ${INSTALL_DIR}/webapps/ROOT.war

Step 6: Ensure that the system user that will run Tomcat has execute and write permissions on the copied WAR file.

Step 7: Run the startup.sh script in the Driven installation directory:

$ cd ${INSTALL_DIR}
$ bin/startup.sh

Step 8: Follow the steps in Installing the Driven CLI Client. The CLI Client must be at the same version as the Driven Server installation to complete the upgrade.

Perform the Migration Process

Prerequisite: The version of your Driven CLI Client must be the same version as the Driven Server.

Step 1: Establish a terminal session with the Driven Server

Depending on data size, the migration can take from seconds to several hours or more. Therefore, use a tool like GNU Screen on a machine that runs all day, preferably on a machine hosting a Driven Server, to persist the console session.

Note	Contact Technical Support if you have questions about establishing a persistent session with a tool like GNU Screen.

Step 2: Start the data migration process

If you are using the CLI Client on the same machine that hosts the Driven Server, enter the following command:
```
driven reindex --start --stay-connected
```
If you are working in a CLI Client that is on a machine that is different from the one that hosts the Driven Server installation, enter the following command. (Substitute 8080 with your Driven Server port number if the server was configured to run with a non-default port number.)
```
driven reindex --hosts ${DRIVEN_SERVER_URL} --port 8080  --start --stay-connected
```

Step 3: Wait for the migration to complete — the terminal will display the message that the reindexing is done and a restart is needed

The CLI Client manages the migration process by communicating with the server and outputs informational messages on the screen as the reindexing proceeds through the following stages:

CREATE_NEW_INDEX
ENTITY
CASCADING
SLICE
BINDING

Tip	The migration of larger installation footprints might require several hours to complete. The CASCADING stage in particular can be lengthy for migrations that span hours.

Step 4: Restart the Driven Server when migration is complete

When the migration process is complete, the CLI displays the following output:

********************************************************
reindex done ( took _duration_ ). webapp restart needed.
********************************************************

Verify Migration and Reindex Status

To check the upgrade and migration status and determine if further action is required, run the following command in the Client CLI home directory:

driven reindex --status

If the response statement is server reindex status: RUNNING_CURRENT, then upgrade and migration were successful and the old indexes are removed.
If the response statement is server reindex status: DELETE_OLD_INDEXES, the upgrade and migration were successful but you need to remove some old artifacts. Keep the cascading_4, entity_4, and slice_4 indexes, but delete other indexes. For more information, see the Elasticsearch Reference documentation about deleting an index.
If the response statement is server reindex status: CREATE_NEW_INDEX, then upgrade was successful but migration was either unsuccessful or not completed.

Note	If the response statement is not one of the three documented above, then either your Driven Server is partially upgraded or there is a mismatch of your Driven Server and the CLI Client. In this case, contact Technical Support before attempting upgrade and migration again.

Tip	The `driven reindex --status` command can be helpful to check on the deployment’s state relative to upgrade and migration if you were not able to see the process through to completion and verification.

Next Topic

Troubleshooting Driven