Installing and Configuring Voyager Behind a Firewall

Introduction

This document provides the procedures for installing and configuring Voyager behind a firewall. There are two sections to the document:

• Downloading and Installing Voyager (requires Internet access)
• Configuring Voyager Behind a Firewall (does not require Internet access)

Scope of this Document

This document does not cover installation of non-voyager components, nor does it provide information about Voyager Server beyond installing and configuring the software.

Voyager Server Installation Check List

Use this checklist to keep track of the required installation steps.

Task	Performed by	Date
Pre-requisite check
Install Voyager Server
Configure Voyager Server
Install ArcGIS COTS
Connect Content Locations
Install Validation Steps

Downloading and Installing Voyager
(Requires Internet Access)

Creating a Voyager Account

Before you can use Voyager, you will need to have an account.

To create an account:

1. Go to http://voyagersearch.com/account/login
2. Enter your Email address to create a new account
   
   
   
   
3. You should get a success message
4. Click Continue
5. You will receive an email with an activation code - you will need this code to complete the registration process
   
   
   
   
6. Click on the link in the email and it will bring over the activation code
   
    
   
   
7. In the form on this page, please complete the rest of the information required for activation of your Voyager account
   
   
   
   
8. You will receive a success message if you have entered all of the information correctly
9. Proceed to the Download link on this page to download Voyager

Downloading Voyager

1. Go to www.voyagersearch.com/download
2. Choose your platform and version, and click Download
3. Download the Voyager Server license. Your license key controls the functionality of the software, so even if you have a Server Pro license, we can adjust that with your license.
   
   
   
   
4. For Voyager server instances, you can also manage your license using the following URL:
   http://localhost:8888/manage/settings/license
5. You can check Voyager's software and system requirements here.

Installing Voyager

Run the Installer

To run the installation, double-click the Voyager executable.The installation wizard guides you through the necessary steps.

Note: You might receive a windows security warning specifying that the application’s publisher is Unknown. This message is safe to ignore.

1. If a previous version of Voyager has been detected on your machine, the Welcome screen gives you the option to install into the existing directory or to a different directory. If you choose to install into a different directory, you will have the ability to choose your installation location from the Select Destination Directory screen; otherwise it will default to the current Voyager install directory.
   
   
   
   
2. Read the terms of the Licensing Agreement and check the first button to indicate agreement.
3. Specify the required location to install Voyager (Voyager writes information to the installation location, so it is important that you have permissions and disk space available at this location)
   
   
   
   
4. Select Voyager Start Menu options and click Next. A dialog box prompts you to specify the Voyager start options.
5. Complete the setup and click Finish
6. Voyager Initial Setup

When you have downloaded and installed Voyager, the Setup Wizard appears the first time you start Voyager.

Entering Your License

Enter your software license using either Option A or Option B as described below:

• Option A - Authorizing for the first time using a new license
  Enter your license and click Install License. Voyager will display a confirmation message once you've entered a valid license.
• Option B - Authorizing using an existing license
  If you already have a license, paste the license key supplied by Voyager into the text box.

Setting Up and Configuring Voyager Behind a Firewall
(Internet Access Not Required)

By default, Voyager works with several data resources, including maps and data, provided over WWW. In order for Voyager to fully function offline or behind your firewall, it is necessary to follow these steps to configure Voyager to use equivalent resources available behind a network firewall where the default resources are limited or are not available.

Configuring Voyager's Appearance - Navigo UI

To configure the Navigo UI:

• Go to Manage Voyage > Settings > Appearance > Navigo UI
  
  

You can configure the following settings:

• Homepage settings
• Placefinder enable/disable
• Footer HTML
• Banner HTML
• Default Credentials
• Mapping

Configuring Voyager to Use a Cached Base Map

Voyager uses a Web map service from Esri or Google as its default base map. However, users with no access to the public internet or those who wish to use their own Web map service can easily create and use an offline cached base map to support spatial searching. The cached base maps can also be moved to a different location (such as to a server behind a firewall).

Caching a Base Map can also be important when Rendering Thumbnail Images from Geometry, as it helps speed up the process.

Creating a New Cached Base Map

To create a new cached base map to use offline:

1. Go to Manage Voyager > Settings > Mapping
   
2. Select Caching Base Map under Add Map Service
   
    
   
   

1. Enter a Name for the Cached Base Map
2. Enter the URL of the map service that you would like to use
3. To apply the WGS84 Coordinate System to your map cache, check WGS84
4. To set a maximum extent for the map, enter the Latitude and Longitude for the map and the zoom Levels for the map service (leave Levels blank to use the full map extent)
5. Click Save
6. Click the Edit icon next to your new cached base map
   
   
   
   
7. Click Manage Cache
   
   
   
   
8. You can Queue individual map levels
   
   
   
   
   • The Map option lets you pick the base map you'd like to cache (when multiple base maps exist)
   • The Threads option lets you increase the thread count i.e. the number of map service instances (the default is 2 - increase this to download tiles faster)
   • Click Cache to start downloading map tiles
   • To stop the process at any tile level, click Stop
   • Queue individual map levels using the Queue link next to each respective level
9. Once caching is complete, refresh the main Voyager page to see your map
10. You can access the downloaded map cache from the Voyager maps folder (default directory is <VoyagerInstallDir>\data\maps)

Moving Cached Base Maps to a Different Location

You can move the entire maps directory or a specific map cache to a different location. This is useful should you need to move the map cache to a drive with more storage space, or to redeploy an existing map cache to a Voyager instance on a different operating system.

1. Copy or move the cached map folder to a the new location. The default location for downloaded map tiles is <VoyagerInstallDir>\data\maps.
2. The configuration settings for the Voyager mapping page are stored in the file dex, located in <VoyagerInstallDir>\data\config\maps.dex. Copy this file from the existing Voyager server to the new Voyager server. If maps.dex is missing or corrupted, simply re-run the steps to cache the base map. Voyager will recognize the existing map cache instead of downloading the map tiles again.

Configuring Geotagging

Voyager's Placefinder function can search using familiar place names instead of only searching by selecting a bounding box on a map. Voyager offers an online gazetteer of 13 million placenames for searching by a location, however Voyager administrators can also create their own local gazetteer to provide search capabilities for users behind a firewall.

The Placefinder is enabled by default and the Home page will show Within and Intersects in the Where is it located? drop-down menu, shown below:

Enabling the Placefinder

To enable or disable the Placefinder:

1. Go to Manage Voyager > Settings > Appearance > Navigo UI
2. Click Show Placefinder Query Box
   
   
   

Configuring the Placefinder

To Configure the Placefinder:

1. Go to Manage Voyager > Settings > Placefinder
2. You can edit the Placefinder configuration in the dialog that appears:
   
   

The Placefinder function cycles through the list, in order of appearance, to try and find matches. The threshold value is used to normalize scoring across different Placefinders with different scoring systems. The default threshold values are Voyager best practices and updating these values should be reserved for advanced administrators.

NOTE: Voyager will ignore Placefinder entries that require an internet connection, for example the Esri Geocoding function will not be available .

Configuring a Custom Gazetteer

Voyager uses Gazetteers for Geotagging and Placefinding (Geotagging extension required). There are two types of gazetteers, Custom and Standard.

• Custom Gazetteer- A custom gazetteer is based on specific data in the index that you use as a source of location information for other data.
• Standard Gazetteer- This is a pre-built gazetteer stored in a separate index (gazetteer), in local or remote Voyager instances.

Adding the Location to use for Geotagging

1. Add a location that contains records with location names or asset IDs (for example) along with a geometry.
2. For that location, identify the index field that has place data that the placefinder will match against. This is commonly meta_NAME or meta_ID. For the sake of clarity, we will refer to this as meta_NAME.
3. Go to the Document Transformers page and set up a Copy Field transformation that copies meta_NAME to a field prefixed with fst_tag_. For example fst_tag_NAME.
4. Build (or rebuild) the index for the gazetteer source.

Searching with a Custom Gazetteer

To search with the custom gazetteer:

1. Go to Manage Voyager > Settings > Placefinder
2. Temporarily disable the Esri geocoding service by changing Enabled to Disabled under the This is done because the service is capable of resolving names that overlap with the country and state names in the custom gazetteer.
3. Click Save to save the placefinder settings.
4. Open the Navigo interface and do a placename search for California. No results should be returned because we just disabled the Esri geocoding service
   
   
   
   
5. Go back to the placefinder settings and add the configuration to enable placefinding with the custom gazetteer:
   
   {
   "type": "Tagger",
   "name": "gazetteer",
   "tag": {
   "custom": {
      "enabled": true,
      "url": "http://<YourVoyagerServerURL>/solr/v0",
      "tagField": "fst_tag_name"
    }
  }
}

After saving the placefinder settings, return to Navigo and re-execute the California search. This time it should yield results as the name California was resolved by the custom gazetteer.

Geotagging by Location vs. Tagging by default

You can configure a Custom Gazetteer to use as a default, or you can configure one for a specific location.

Configuring Default Geotagging Settings

To use a Custom Gazetteer for all locations:

• Go to Manage Voyager > Discovery > Discovery Configuration
• Select Geotag from a Custom Gazetteer

Configuring Geotagging for a Specific Location

• Go to Manage Voyager > Discovery > Locationsand click the Edit icon button to the location you want to geotag.
• Select Geotag from a Custom Gazetteer on the Geotag tab

Configuring Custom Geotagging Parameters

The configuration steps are the same for both of the options above. Enter the following information:

• Enter the URL for a Voyager Location or Query Parameter
  This is the URL for location information, and can be copied directly from the address bar of a Voyager search results page.
• Select the Field Containing Location Information
  This is a field created using Voyager’s Document Transformer geotagging step.
• Select the Fields to Copy from the Gazetteer
  Additional fields to be copied from the gazetteer to the target documents. For placefinding, it is important to copy the bbox and/or geo fields
• Select the Text Field to Geotag
  Any text field in a document can be geotagged. Most commonly this is the text field.
• Check Geotag Documentsto enable tagging documents with bounding box (bbox) or geometry (geo) fields.
• Click Save to save your changes.

Geotagging Records

To apply tagging with the Gazetter, you need to rebuild either the entire index or just the specific location, as appropriate.

To rebuild the index for a location:

1. Go to Discovery > Locations and click the Manage icon next to that location
2. Select Rebuild from the list of Actions

To rebuild the entire index:

1. Go to Manage Voyager >Discovery > Status
2. Click Scan All Locations

Viewing Tagged Data

To view tagging information once the index has been rebuilt:

1. Return to the search results that include the location
2. Click Show Detail Page for an individual record
3. The geotags are displayed under the Locations section of the details page. On Navigo the Locations are found by clicking the Relationships button on the search result details page. 
4. Look for location information, for example bbox values, in the list of metadata

Adding Locations

Given connectivity exists between the server Voyager is installed on and the content you want to index follow these procedures to index your various data types.

http://help.voyagersearch.com/doc-203513693-adding-discovery-locations

Memory Management

Voyager's default memory settings may not be optimal as the index increases in size, and it may be necessary to increase the memory limits.

To check the current memory setting:

1. Go to Manage Voyager > System > Info
2. Current memory use is listed at the bottom

To Modify Memory Settings:

• Use notepad to open <install location>\app\voyager.vmoptions
• Edit the the -Xmx file to change the default value of 1024M to a larger value. See notes below

Notes

When adding memory, more is not always better. Voyager runs in a java virtual machine and uses a garbage collector to manage memory. If the amount of memory is set exceptionally high, beyond what is actually needed, the garbage collector will have to do extra work. It's best to make incremental adjustments such as 500MB or 1GB at a time.