Setting up and Configuring Voyager Behind a Firewall

Owned by Heather Geyer
Aug 04, 2022
7 min read

(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 tilesTo 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, Customand 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 ParameterThis 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 InformationThis is a field created using Voyager’s Document Transformer geotagging step.

  • Select the Fields to Copy from the GazetteerAdditional 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 GeotagAny 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.