Discovery Search Install & Upgrade Process

Purpose

Discovery Search uses Internet Information Services (IIS) for Windows® Server and Windows Authentication with Kerberos to authenticate a user from an internet browser. This guide outlines Shinydocs™ Discovery Search prerequisites, the process for installing with or without Kerberos usage, and upgrade steps.

Prerequisites

Hardware

We recommend load testing Discovery Search in a staging environment before promoting it to production, as small intricacies in an environment may have an impact on performance and end-user experience. After initial load testing, adjust your hardware based on the needs of the environment.

For example, if your CPU utilization on machines running Discovery Search is above 95% under load, you should upgrade the number of CPU cores allocated to the machine.

Performance for Discovery Search is primarily based on the performance of your Indexing Cluster. To help identify performance bottlenecks, Discovery Search can log the response times of fetching data from the index and delivering the results to the end user.

Recommendation for up to 1000 Users

Recommendation for scaling to over 1000 users

Discovery Search scales best for over 1000 users with the use of load balancing. We recommend setting up multiple Discovery Search instances behind a load balancer(s) and using your monitoring application of choice (for example, Windows Performance Monitor) to track resources.

For more information, see: https://techcommunity.microsoft.com/t5/core-infrastructure-and-security/iis-best-practices/ba-p/1241577

Load Balancing

Discovery Search works with load balancers to reroute traffic based on usage. Load balancing can be done with Azure Load Balancer or Azure Application Gateway.

As Discovery Search is hosted in IIS, we recommend following your organization’s current policy on load balancing IIS web applications/sites. If your Discovery Search is load-balanced, we recommend setting up and configuring on one machine, then replicating to other machines to ensure a consistent experience.

Software

Discovery Search is an application that runs on Microsoft® Internet Information Services (IIS).

Internet Information Services (IIS) Features 

Before installing Discovery search, please enable and install the following Windows Roles and Features. These can be enabled in Windows Server Manager > Add Roles and Features Wizard.

Additional Admin Panel Requirements

To ensure Admin Panel pages save successfully in Discovery Search, please ensure that IIS_IUSRS or the application pool user has write access to the following directories:

• Configuration

• Scripts

And the following file:

• Web.config

Installing Discovery Search

Without Kerberos pass-through

Create and Configure Discovery Search Site

1. Extract shinydocs-discovery-search-<version>.zip to the directory where you want the application to reside

2. On the extracted folder, go to Properties>Security 

3. Add IIS_IUSRS to the permissions of the folder and give full control

4. Ensure IIS_IUSRS or the Application Pool user has write access to the Scripts directory and the Web.config file

5. Open Internet Information Services (IIS) Manager

6. Create a new site

7. Name your site Discovery Search

8. Change the physical path to the extracted folder from step 1

9. Set the port you wish to use (80 is likely taken from the default IIS site)

10. Click on the site in the tree

11. Double-click Authentication under IIS 

12. Disable Anonymous, and Basic Authentication, and Forms Authentication

13. Enable Windows Authentication and ASP.NET Impersonation

14. Within the IIS Manager, right-click on the Discovery Search site and click Explore to view the site folder structure

15.  Access and edit the Web.config file

    1. Change the IndexServerUrl key value to where the index is located and the port for it (default is 9200)

    2. [not required for versions 1.9 and later] In the IndexName key, add the indices you want to search, separated by a comma

    3. Ensure SettingsEncryptionKey is changed from “somebody change me” to a new value (for example, best practice is a minimum of 12 characters, including letters, numbers, and special characters)

    4. For clustered systems, ensure the new SettingsEncryptionKey value is the same for all systems within a cluster

    5. Confirm ActiveDirectoryAdminGroup is configured

    6. Configure SettingsIndexName to a value if desired

    7. For clustered systems, ensure the SettingsIndexName value is the same for all systems with a cluster

    8. Save changes

16. Open Windows command and restart IIS and run the following command: iisreset /noforce

Connect Discovery Search to an index

1. Launch a browser and open the new Discovery Search site (for example, http://localhost:9200/admin)

2. Navigate to Roles

3. From the Default Role, click Edit

4. Select Sources Configuration

5. Click + Add source

6. Enter the name the content source in Name

7. In Indices, enter the name of the index that correspond to the specified content source in Discovery Search

8. Select the Language that the title will be displayed in

9. Enter the Title that will represent this index throughout the Discovery Search UI

10. Click + Add source to add another source index to this role

11. Once all sources are added, save changes

12. Refer to Configuring Roles for details on configuring user roles

Each role can have different values for the above settings, as well as variances in what sources are available to each role

With Kerberos pass-through

Kerberos is a computer-network authentication protocol that works based on tickets that allow nodes to communicate over a non-secure network, to prove their identity to one another in a secure manner.

For more information on how to set up your Windows Server environment to support Shinydocs Discovery Server with Kerberos pass-through (double-hop authentication), see Kerberos Authentication Setup.

Upgrading Discovery Search

Prerequisites

1. Download Discovery Search from Shinydocs Collab

2. Install in a new folder within the same directory as the prior installation

3. Set IIS to target the new folder

We recommend that the Web.config file from the previous version of Discovery Search is saved as a reference for the steps in the Configure web.config section of this guide.

Upgrading from 1.9.0 to 1.10.0 (or later)

Install Discovery Search by configuring web.config

1. Copy all settings from the 1.9.0 web.config file and paste in the designated area in the new web.config file, as suggested by the following comments:

   XML

       <!-- For Migration, place all settings from a previous version of the web.config not already set above; below this line.  They will be migrated into the index on first startup, and then can safely be removed from disk. -->
       <!-- For settings that were previously in the Configuration Directory, leave them there until after first startup, they will be migrated to the index.  Once complete, you can remove them from disk -->

2. Update the following parameters in the new config file to match the value from the previous config file:

   1. SettingsEncryptionKey

   2. IndexServerUrl

   3. SettingsIndexName

   4. ActiveDirectoryAdminGroup

Typically, any current settings not already in the configuration file should be copied. However, if you didn’t, reasonable defaults would be applied which can then be configured through the admin pages.

Restart ISS, verify installation, and clean up temp files

1. Restart IIS

2. Launch a browser and open the new Discovery Search site (for example, http://localhost:9200/admin)

3. Once Discovery Search 1.10.0 or later is live and accessible, remove all temp files under C:\Windows\Microsoft.NET\Framework64\v4.0.30319\Temporary ASP.NET Files\root\

Upgrading from 1.8.0.2 and earlier to 1.9.0 (or later)

Upgrading to Discovery Search 1.9.0 or later from an earlier version changes the structure of saved settings and introduces role-based access control (RBAC). These steps must be followed to ensure data and settings are migrated into the new Discovery Search structure.

Migrate configuration and template folders

All configurations and templates from your pre-1.9.0 installation of Discovery Search can be migrated as part of the upgrade process. The following steps must be completed before the first launch of the upgraded Discovery Search.

Migrate configuration folder

1. Copy the entire folder Configuration into Discovery Search 1.9 (or later) directory

Migrate templates folder

1. Within the older Discovery Search directory, navigate to the folder titled Scripts/templates

2. Copy the folder

3. Paste this folder into the new Discovery Search directory within /Scripts

Migrate custom logos

1. Within the older Discovery Search directory, navigate to the folder titled Content/Custom

2. Copy the folder

3. Paste the folder into the new Discovery Search directory within /Content

4. Overwrite when prompted

Migrate custom infographics

1. Within the older Discovery Search directory, navigate to the folder titled Content/About

2. Copy the folder

3. Paste the folder into the new Discovery Search directory within /Content

4. Overwrite when prompted

Migrate custom lists

1. Custom lists that have been created to support Advanced Search features must be either;

   1. copied and re-saved in the same location within the new Discovery Search directory; or,

   2. saved to a new location (In this case, the path to the file must be updated in your new configuration)

Configure web.config

1. Copy all settings from the 1.9.0 web.config file and paste in the designated area in the new web.config file, as suggested by the following comments:

   XML

       <!-- For Migration, place all settings from a previous version of the web.config not already set above; below this line.  They will be migrated into the index on first startup, and then can safely be removed from disk. -->
       <!-- For settings that were previously in the Configuration Directory, leave them there until after first startup, they will be migrated to the index.  Once complete, you can remove them from disk -->

2. Update the following parameters in the new config file to match the value from the previous config file:

   1. SettingsEncryptionKey

   2. IndexServerUrl

   3. SettingsIndexName

   4. ActiveDirectoryAdminGroup

Typically, any current settings not already in the configuration file should be copied. However, if you didn’t, reasonable defaults would be applied which can then be configured through the admin pages.

Restart and verify the installation

1. Restart IIS

2. Launch a browser and open the new Discovery Search site (for example, http://localhost:9200/admin)

Connect Discovery Search to an index

1. Launch a browser and open the new Discovery Search site (for example, http://localhost:9200/admin)

2. Navigate to Roles

3. From the Default Role, click Edit

4. Select Sources Configuration

5. Click + Add source

6. Enter the name the content source in Name

7. In Indices, enter the name of the index that correspond to the specified content source in Discovery Search

8. Select the Language that the title will be displayed in

9. Enter the Title that will represent this index throughout the Discovery Search UI

10. Click + Add source to add another source index to this role

11. Once all sources are added, save changes

12. Refer to Configuring Roles for details on configuring user roles

Each role can have different values for the above settings, as well as variances in what sources are available to each role.

Verify and cleanup the installation

1. Confirm the settings and configurations for the Default Role in the Discovery Search Admin Panel, under Roles, migrated successfully, including:

   1. Templates

   2. Advanced Search

   3. Filters

   4. Source Groups

   5. Loader messages

   6. any other customized templates

2. Once Discovery Search is live and accessible, the following can be removed:

   • Configuration folder

   • Templates folder

   • All temp files under C:\Windows\Microsoft.NET\Framework64\v4.0.30319\Temporary ASP.NET Files\root\

   • All web.config settings that were pasted between

     • XML

       <!-- For Migration, place all settings from a previous version of the web.config not already set above; below this line.  They will be migrated into the index on first startup, and then can safely be removed from disk. -->
       <!-- For settings that were previously in the Configuration Directory, leave them there until after first startup, they will be migrated to the index.  Once complete, you can remove them from disk -->