Migrating to Voyager 1.9.12

Owned by Heather Geyer
Last updated: Aug 12, 2022
5 min read

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 standalone 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 standalone application:

  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.