Migrating to Voyager Search 1.9.12

If you have any questions about this migration or about this release, please do not hesitate to contact us - We’re here to help at support@voyagersearch.com

Backing up your Index

Before migrating your Voyager Index to version 2.0, you should always create a backup Snapshot.

Upgrade Strategies

You can migrate Voyager using a parallel (side-by-side) model, or you can migrate Voyager in place. We recommend performing this upgrade as a side-by-side (parallel) migration, as shown in the diagram below.  

Voyager Application vs Voyager Service

Voyager Server can be installed either as a stand-alone application or as a Windows Service. Steps to upgrade in each of these configurations are described in the next sections.

Side-by-Side Upgrade - Voyager Application

This approach leaves your existing Voyager installation in place until you can confirm that the new version is up and running to your satisfaction. Installation instructions are available here.

To migrate Voyager side-by-side when Voyager is installed as a stand-alone appplication:

1. Make a copy of your Voyager Search content (including the Config, Data, Index, Meta and Maps folders in your data directory, and optionally your Logs and Temp directories) for the new version to use. (You might need to stop your existing Voyager briefly to make this copy).
2. Use our Windows installer to install Voyager Search 2.0 into a different directory. (Optionally, you may run Voyager Search 2.0 at this point with the default configurations to test that your installation was successful. If you have installed on a new machine, you may need to update your license).
3. Configure the new Voyager Search 2.0 to use the content above using the voyager.vmoptions file. This is often just a matter of setting the -Ddata.dir parameter, but can involve setting other data location parameters if your voyager deployment configures data directory sub-locations separately.
4. Restart Voyager Search 2.0 (this upgrades the content and configurations from previous versions
5. Confirm that Voyager Search 2.0 is functioning properly with your previous configurations and content.
6. Promote your Voyager Search 2.0 installation by configuring the default application port(s), and redirecting Domain Name Server and Load Balancers, etc. accordingly.
7. Retire your previous Voyager Search instances(s)

Side-by-Side Upgrade - Voyager Service

To migrate Voyager side-by-side when Voyager is installed as a service:

1. Make a copy of your Voyager Search content (including the Config, Data, Index, Meta and Maps folders in your data directory, and optionally your Logs and Temp directories) for the new version to use
2. Stop the current Voyager Service
3. Open a command prompt
4. Go to the app directory in the Voyager installation directory, for example
   C:\voyager\server_1.9.x\app
5. In the app directory, enter VoyagerService.exe/uninstall
6. In the app directory, enter VoyagerService.exe/install
7. Configure the new Voyager Search 2.0 to use the content above using the voyager.vmoptions file. This is often just a matter of setting the -Ddata.dir parameter, but can involve setting other data location parameters if your voyager deployment configures data directory sub-locations separately.
8. Restart the Voyager service (this upgrades the content and configurations from previous versions)
9. Confirm that Voyager is functioning properly with your previous configurations and content.

Upgrade in Place

A side-by-side migration to Voyager Search 1.9.12 might not be feasible for organizations with larger Voyager Search indexes. In this case, an in-place migration is suitable. 

More detailed instructions are available here. Briefly, in this scenario:

1. Use our Windows installer to install Voyager Search 1.9.12 into the existing instance.
2. When this installation is complete, start Voyager Search 1.9.12 (this automatically upgrades the content and configurations from previous versions)

NOTE: An in-place migration is also suitable for organizations with multiple Voyager Search installations if one or more side-by-side migrations have been successful. 

Which Voyager Versions Can I Migrate to 1.9.12?

• We have tested side-by-side and in-place migrations to Voyager Search 1.9.12 from all supported 1.9.x release versions (1.9.5 through 1.9.11).
• We have not tested migration from versions before 1.9.5. If you have a Voyager version that predates 1.9.5, please contact support@voyagersearch.com

In-Depth Migration Information

The rest of this document is organized into sections that discuss migration to Voyager Search 1.9.12 by a particular topic (Saved Searches, Security Tokens, etc.). You only need to review the topics that are relevant to you.

In each section, we note which (previous) versions are affected by this migration topic.

Voyager Setup Wizard

(ALL PREVIOUS VERSIONS)

• The Voyager Setup Wizard will run if site.dex flags the setup as incomplete (not SetupComplete=true), or if the contents of the /config directory are not completely copied from your previous Voyager instance.
• In the preferred migration scenarios that we describe above, neither of these events are likely. In their unlikely occurrence, you may need to relicense and/or redefine your Voyager Locations.

Re-licensing Voyager

(ALL PREVIOUS VERSIONS)

• Voyager will not run without a valid license. If your /config/license.dex file is missing or invalid, you will be prompted to enter a new licence key before proceeding. Coincident with version 1.9.7, we moved our licensing system to a new platform.
• This is one of the reasons we recommend a side-by-side migration.

Redefining Voyager Locations

(ALL PREVIOUS VERSIONS)

• After successfully licensing Voyager, the Setup Wizard may prompt you to identify new locations for Discovery. It is not necessary to add any locations here, as existing locations defined in your previous Voyager configurations will persist. You can simply, click Next on this screen to initiate the discovery process.
• NOTE: This might not be ideal for clients with very large indexes. You can bypass the Discovery process by clicking Skip this Step at the bottom left of the page. Keep in mind that Discovery locations and processes can always be configured later using Voyager's Management UI.
• There are certain features in this release that will compel users to reindex some of their data. These are discussed in the next section.

Rediscovery

Indexing Geometry

(Version 1.9.5 and earlier)

• Starting in Voyager 1.9.6, users can save full geometry for indexed documents in addition to or in place of the document's existing BBOX. Indexing full geometries allows for more accurate spatial queries, but requires more space to store the index. For this reason, we allow users to define some degree of global or location-specific generalization for indexed geometries. Read this article for more about index sizing considerations.
• You do not need to index geometries; new features that leverage this will work against the existing BBOXes. However you must reindex any location(s) whose records' geometry you wish to store.
• See this article for more information on Spatial Index settings, and this article for information on configuring Discovery.

Display Configurations

(Versions 1.9.5-1.9.8)

• Voyager version 1.9.9 introduced a new approach to configuring and managing Display Templates and Saved Searches. Users will notice that the View > Settings menu is gone from the Classic UI. Saved Searches and Display Templates are now accessed from the My Displays section in the Manage UI.
• Conceptually, these items still behave much the same:
• Display Configurations manage which index fields are shown in which elements of different display types (e.g. Table View columns or Details Page names)
• Saved Searches apply those display configurations to text and/or facet queries for specific index records.
• The new UI makes managing and defining those prescribed searches a much better experience, and relocates that functionality to a more appropriate location in the software. 

NOTE: Your existing Display Templates and the Saved Searches that use them will be migrated automatically to 1.9.12. For more information on this feature, please see this article. 

Saved Searches

(ALL VERSIONS)

• All of your Saved Searches from your previous version of Voyager will appear in your 1.9.12 instance after you have upgraded successfully.  
• If you want to remove old saved searches and start over with the out-of-the-box Saved Searches in 1.9.12, clear all of the Saved Searches in your pre-1.9.12 instance before starting the migration.
• Starting in version 1.9.6, Voyager introduced several new features that allow you to enhance and classify your records with tags, flags (e.g. is “featured”), and custom field edits. You can learn more about these features here.
• Alongside these new features, Voyager includes several new pre-defined Saved Searches that leverage these attributes in their queries.

Federation

Federation to Heterogenous Versions

(ALL VERSIONS)

• Federation to remote Voyager instances continues to be supported in version 1.9.12. However, users may experience unexpected behavior communicating with versions at or earlier than 1.9.4.
• Officially, remote federation with versions back to 1.9.5 is supported, with federation to later versions strongly preferred.

References to the LOCAL Catalog

(ALL VERSIONS)

• Beginning with version 1.9.6, references to the local catalog (ID = LOCAL) in federated index configurations will always use the application's base URL (http://<server>:<port>/<context>).
• This avoids issues that occurred previously if the instance referred to in the LOCAL configuration ceased to exist.

Custom Processing Tasks

New Task Folder Structure

(1.9.5 and earlier)

• In versions of Voyager Search before 1.9.6, Python (.PY) processing and configuration (.INFO.JSON) files were saved in the <voyagerinstall>\app\tasks\ directory (\voyager_tasks\ and \info\, respectively).
• In Voyager Search 1.9.6 and later, these files are stored in <voyagerinstall>\app\py\processing (\tasks\ and \info\, respectively).
• After a migration from a version before 1.9.6 to 1.9.12, customizations to existing .PY and INFO.JSON files will persist, but you will need to move them into the new folder structure in your upgraded version.

References to Task Utility Modules

(1.9.5 and earlier)

• In versions of Voyager Search before 1.9.6, .PY utility modules for Voyager’s processing framework were imported from the voyager_tasks module.
• In version 1.9.6 and later, this module has been renamed tasks, and legacy references to voyager_tasks are no longer valid. In any custom processing .PY files, references should point at the tasks module

Index Query Boost (bq=) Settings

Replace Empty Query Boost Parameters

(1.9.5 and earlier)

• To leverage the tagging, flagging and user field editing features introduced in Voyager 1.9.6, we made a minor adjustment to the default Index Query settings.
• The Boost Query (bq=) parameter is useful for pushing records that match the specified criteria to the top of Voyager’s results set.  With version 1.9.6 and later, any custom bq= settings are preserved, unless the customization is an empty bq=. To add or append to Voyager 1.9.6 (and later) default Boost Query settings, edit the existing value, and update the bq= parameter value accordingly. The 1.9.6 (and later) default string is: 
  bq=tag_flags:[* TO *]^5+description:[* TO *]^5+hasMetadata:true^3+hasThumb:true^3

Security(.dex) Settings

(1.9.6 and earlier)

• Voyager's security settings are written to the file security.dex in the /data/config/ directory. All security settings migrate from 1.9.7 to 1.9.12 without issue; however two small issues exist when migrating from versions 1.9.5 and 1.9.6

Java Web Token (JWT) Parameter

• Voyager uses JWTs to enable authentication & group membership information to be passed between remote members of a Voyager federation. For more information on how and why to configure shared authentication among Voyager federates, please see this article. 
• Migrating from both Voyager version 1.9.5 and 1.9.6, any JWT parameters saved in security.dex do not get upgraded. Users must regenerate the JWT (on each member of the federation) using the instructions in the article above. 

Windows Realm / Active Directory (AD) Group Syntax

• Voyager also stores definitions Windows Realm / AD Group configurations in security.dex.  Configurations for Voyager versions 1.9.5 and 1.9.6 are not compatible with Voyager version 1.9.12. There are no issues with compatibility migrating from Voyager versions 1.9.7 through 1.9.11.
• The resolution to this issue is dependent on your Voyager version. 

If you are running Voyager version 1.9.5 

For each of the AD user groups defined in security.dex, change the attribute name "fqn" to "name" and "sid" to "id":

Security.dex 1.9.5 (example):

{ "fqn": "VOYAGER\\VoyagerSearchUsers", "sid": "S-1-5-21-3031513283-2212486641-2158712043-1138" }

Security.dex 1.9.12 (example):

{ "name": "VOYAGER\\VoyagerSearchUsers", "id": "S-1-5-21-3031513283-2212486641-2158712043-1138" }

If you are running Voyager version 1.9.6 

For each of the AD user groups defined in security.dex, change the attribute name "fqn" to "name" and remove the "sid" attribute entirely.

Security.dex 1.9.6 (example):

{ "fqn": "VOYAGER\\VoyagerSearchPublic", "sid": "S-1-5-21-3031513283-2212486641-2158712043-1110", "id": "S-1-5-21-3031513283-2212486641-2158712043-1110" }

Security.dex 1.9.12 (example):

{ "name": "VOYAGER\\VoyagerSearchPublic", "id": "S-1-5-21-3031513283-2212486641-2158712043-1110" }