LucidWorks Search can be stopped with the scripts available in {{$LWE_HOME/app/bin}}. Use either {{stop.sh}} or {{stop.bat}} depending on your operating system.
A backup of your existing installation can be made by copying the entire $LWE_HOME directory to a parallel location. If your installation has been made in a directory called {{/usr/local/LucidWorksEnterprise}}, then in Unix, for example, the command would be:
{code:borderStyle=solid|borderColor=#666666}
cp -r /usr/local/LucidWorksEnterprise /tmp/lwe-old-backup
{code}
You can name the backup whatever you'd like, as long as you remember it later if you need it.
Now is also a good time to make note of any customizations that will be over-ridden by the upgrade, if you haven't done so already. For details of these changes, see the [Upgrade Notes] for your version.
{topofpage}
h6. Step 2: Install the New Version of LucidWorks
Follow the steps outlined in the [sections on installing LucidWorks|lweug:Installation] to install the new version of LucidWorks. This can be done in any location on your server, but you should change the default path if your existing LucidWorks is already installed there. You can choose the same ports as are used in your existing installation: this installation will only be used to get an updated {{app}} directory, the MetadataUpgradeTool, and the IndexUpgradeTool (See [Step 3|#step3] and [Step 4|#step4] below).
{warning}
Do not install the new version of LucidWorks Search over your existing installation!
{warning}
When the installer asks if you would like to start the new version of LucidWorks, say no (uncheck the box).
The instructions from here on will refer to the top level of this installation as {{$LWE_NEW}}.
{topofpage}
{anchor:step3}
h6. Step 3: Run the MetadataUpgradeTool
The MetadataUpgradeTool is found in the {{$LWE_NEW/app/migration_tools}} directory. It will update your configuration files to the proper format for the new version and will also move the user database from the {{app}} dir to the {{data}} dir if it still exists in the old location.
To run it, issue this command:
{code:borderStyle=solid|borderColor=#666666}
$ java -jar $LWE_NEW/app/migration_tools/MetadataUpgradeTool.jar -verbose -lwe_conf_dir <existing conf dir>
-lwe_app_dir <existing app dir> -lwe_data_dir <existing data dir>
{code}
The parameters {{\-lwe_conf_dir}}, {{\-lwe_app_dir}}, and {{\-lwe_data_dir}} are required and should point to the {{$LWE_HOME/conf}}, {{$LWE_HOME/app}} and {{$LWE_HOME/data}} directories, respectively, of your existing LucidWorks application.
The parameter {{\-verbose}} is optional, but highly recommended. It allows the full output of the tool to show on-screen in case there are problems or failures. If support is needed after using the MetadataUpgradeTool, Lucid Imagination will request this output. The output will look something like:
{code:borderStyle=solid|borderColor=#666666}
### Upgrading format of collections.yml ...
Writing upgraded collections.yml
### Upgrading similarity configuration in Solr schema ...
Upgrading similarity configuration in /Applications/LucidImagination/lwe2.0.1-upgrade/conf/solr/cores/collection1_0/conf/schema.xml
Writing upgraded /Applications/LucidImagination/lwe2.0.1-upgrade/conf/solr/cores/collection1_0/conf/schema.xml
Upgrading similarity configuration in /Applications/LucidImagination/lwe2.0.1-upgrade/conf/solr/cores/LucidWorksLogs/conf/schema.xml
Writing upgraded /Applications/LucidImagination/lwe2.0.1-upgrade/conf/solr/cores/LucidWorksLogs/conf/schema.xml
### Upgrading field mapping configuration in solrconfig ...
Processing /Applications/LucidImagination/lwe2.0.1-upgrade/conf/solr/cores/collection1_0/conf/solrconfig.xml ...
Writing upgraded /Applications/LucidImagination/lwe2.0.1-upgrade/conf/solr/cores/collection1_0/conf/solrconfig.xml
Processing /Applications/LucidImagination/lwe2.0.1-upgrade/conf/solr/cores/LucidWorksLogs/conf/solrconfig.xml ...
Writing upgraded /Applications/LucidImagination/lwe2.0.1-upgrade/conf/solr/cores/LucidWorksLogs/conf/solrconfig.xml
### Removing old autocomplete data files...
### Upgrading UI DB location...
Moved /Applications/LucidImagination/lwe2.0.1-upgrade/app/webapps/lwe-ui/WEB-INF/db/production.sqlite3
to /Applications/LucidImagination/lwe2.0.1-upgrade/data/lwe-ui
### Upgrading UI DB...
Executing UI DB upgrade
== AddExternalProtocolToSettings: migrating ==================================
-- change_table(:settings)
-> 0.0060s
== AddExternalProtocolToSettings: migrated (0.0070s) =========================
{code}
{warning}
If you have created any [collection templates|lweug:Using Collection Templates] they *will not* be upgraded with the MetadataUpgradeTool. It's recommended that all templates created with previous versions be recreated from scratch using a new or upgraded collection.
{warning}
{note}
One of the changes from v2.0 to v2.1 was to change the names of the data source types "S3" and "S3N". The "S3N" type, for Amazon over S3, is now known as "S3". The former "S3" type, for a Hadoop Filesystem on S3, is now known as "S3H". During the upgrade process, these types will be converted automatically.
However, there is a new requirement for these types of data sources that the value for the URL must include a trailing slash if the URL points to a directory of files and not to a single resource. This is not done automatically by the upgrade. In order to successfully crawl an existing "S3" or "S3H" data source after upgrading, the trailing slash must be added manually if the path specified is not to a single file or resource.
{note}
{topofpage}
{anchor:step4}
h6. Step 4: Upgrade the Indexes or Delete Them
The MetadataUpgradeTool only upgrades configuration and other system files. However, the search indexes also need to be upgraded as a separate step. If, however, the indexed content is not needed, the indexes can be simply deleted instead of upgraded.
_Upgrading the Indexes_
In order to upgrade an index from an earlier version of LucidWorks, the Index Upgrade Tool should be run. This tool is found under {{$LWE_HOME/app/migration-tools/}} in a .jar file called {{IndexUpgradeTool.jar}}.
{warning}
It is recommended to run this Upgrade Tool only after consultation with [Lucid Imagination Support|mailto:cases@lucidworks.com?subject=Upgrade Help] to be sure you understand the full ramifications of running this tool on your local, customized, index.
{warning}
While we have provided this index upgrade tool to help you avoid re-indexing your data, it is recommended to do so with every migration to a new version.
Before running the tool, you should make sure LucidWorks is not running to ensure there are no indexing processes taking place while performing the upgrade.
To run the tool, open a command line interface, navigate to the {{$LWE_NEW/app/migration_tools}} directory and issue the command:
{code:borderStyle=solid|borderColor=#666666}
$ java -jar IndexUpgradeTool.jar [options] <sourcedir> <destinationdir>
{code}
The {{<sourcedir>}} parameter is the existing index that will be upgraded and moved to the {{<destinationdir>}}. Unlike the MetadataUpgradeTool, which updates configuration files in place, the IndexUpgradeTool makes a copy of the index while upgrading it. The {{<sourcedir>}} is {{$LWE_HOME/data/solr/cores/}}{{{}{_}collection{_}{}}}{{/data/index}} (where _collection_ is the name of the collection to be upgraded. The {{destinationdir}} should be a temporary location (preferably a directory, such as /tmp/index-upgrade, as the output is a number of raw index files).
{tip}
The IndexUpgradeTool can upgrade the index for one collection at a time. If there are multiple collection in the origin LucidWorks installation, these would each need to be converted separately. By default, there are at least two indexes: the one that contains your data (called _collection1_ at initial installation) and one that indexes log data called LucidWorksLogs. Don't forget to upgrade the LucidWorksLogs collection or delete the index - skipping that collection will cause LucidWorks to fail on restart.
{tip}
There is currently one option that can be used with the IndexUpgradeTool, which is {{\-checkindex}}. This will run Lucene's checkindex tool to validate that the index is correct. This is a good idea to do, especially for systems already in production, but will add time to the upgrade process.
The output of the tool is a number of index files in the location you specified with the {{<destinationdir>}} parameter. Once the tool has finished, delete the existing index files for each collection (found under {{$LWE_HOME/data/solr/cores/}}{{{}{_}collection{_}{}}}{{/data/index}}) and copy the new index files for each collection to the {{index}} dir.
_Deleting the Indexes_
If the index files are not particularly needed, which may be the case for the LucidWorksLogs collection particularly, they can be deleted. To do so, delete all of the subdirectories found under {{$LWE_HOME/data/solr/cores/}}{{{}{_}collection{_}{}}}{{/}} for each collection.
{info:Spell Check Indexes}
If you are using the DirectSpellChecker, which is the LucidWorks Search default spell check implementation, your spell check data will be recreated automatically with either index upgrade method described above (i.e., either by re-indexing all content or upgrading the index with the IndexUpgradeTool). This is because the DirectSpellChecker uses the main index to create spelling suggestions.
If, however, you have changed the default implementation and are using the IndexBasedSpellChecker, your spell check data is not incorporated with the main index, but instead stored as a separate index. In this case, these indexes will not be upgraded with the IndexUpgradeTool (nor deleted by deleting the main index) and may cause problems when restarting LucidWorks. If possible, these indexes should be deleted and rebuilt after the main index has been upgraded.
{info}
{topofpage}
h6. Step 5: Update the {{$LWE_HOME/app}} dir
Neither the MetadataUpgradeTool nor the IndexUpgradeTool update the program files that make up the LucidWorks application. These need to be updated manually by replacing the {{app}} directory in the original installation with the {{app}} directory from the new LucidWorks Search installation. To do this, delete the original {{$LWE_HOME/app}} and copy the {{$LWE_NEW/app}} directory to {{$LWE_HOME}}. Assuming default locations of the installations, the sequence would be:
{code:borderStyle=solid|borderColor=#666666}
$ rm -r /LucidWorks/LucidWorksSearch/app
$ cp -r /LucidWorks/LWS-newVersion/app /LucidWorks/LucidWorksSearch
{code}
...