{"type":"doc","content":[{"type":"extension","attrs":{"layout":"full-width","extensionType":"com.atlassian.confluence.macro.core","extensionKey":"markdown","parameters":{"macroParams":{"__bodyContent":{"value":"# The Locator 6.4.0 Installation Guide\n\n- [Introduction](#introduction)\n - [Target Audience](#target-audience)\n - [Architectural Overview](#architectural-overview)\n - [Limitations](#limitations)\n - [Browser Support](#browser-support)\n - [End User License Agreement](#end-user-license-agreement)\n- [Prerequisites](#prerequisites)\n - [Gateway Hostname](#gateway-hostname)\n - [Hardware Requirements](#hardware-requirements)\n - [Operating System](#operating-system)\n - [Content Handler](#content-handler)\n - [Anti-Virus Programs](#anti-virus-programs)\n - [Host Server Ports](#host-server-ports)\n - [License](#license)\n - [HTTPS](#https)\n - [gMSA Account](#gmsa-account)\n - [User Authentication](#user-authentication)\n - [Deciding Authority Service Authentication Method](#deciding-authority-service-authentication-method)\n - [Active Directory Prerequisites](#active-directory-prerequisites)\n - [Azure Active Directory Prerequisites](#azure-active-directory-prerequisites)\n - [Microsoft SQL Server](#microsoft-sql-server)\n - [Firewall Openings](#firewall-openings)\n - [IP Blocking](#ip-blocking)\n - [Prerequisites for Optional Features](#prerequisites-for-optional-features)\n- [Installing](#installing)\n - [Installation and Restart Time](#installation-and-restart-time)\n - [Installation Drives and Directories](#installation-drives-and-directories)\n - [Running the Install Script](#running-the-install-script)\n - [The Install Script Menu](#the-install-script-menu)\n - [Saga](#saga)\n - [Database](#database)\n - [Gateway](#gateway)\n - [Languages](#languages)\n - [Solr](#solr)\n - [Report Engine](#report-engine)\n - [Lingo](#lingo)\n - [Metrics](#metrics)\n - [Personal Assistant](#personal-assistant)\n - [Smart Classifier](#smart-classifier)\n- [Post-Install Configuration](#post-install-configuration)\n - [Configuring the Authority Service](#configuring-the-authority-service)\n - [Active Directory](#active-directory)\n - [Azure Active Directory](#azure-active-directory)\n - [Managing Users and Roles](#managing-users-and-roles)\n - [Connector Management](#connector-management)\n - [Installing Connectors](#installing-connectors)\n - [Configuring Connectors](#configuring-connectors)\n - [Upgrading Connectors](#upgrading-connectors)\n - [Uninstalling Connectors](#uninstalling-connectors)\n - [Secondary User Authentication](#secondary-user-authentication)\n - [Custom Branding](#custom-branding)\n - [Private Certificate Authority](#private-certificate-authority)\n - [Major Version Upgrades](#major-version-upgrades)\n - [Upgrading from major version 5 to 6](#upgrading-from-major-version-5-to-6)\n - [Upgrading from major version 4 to 5](#upgrading-from-major-version-4-to-5)\n - [Upgrading from major version 3 to 4](#upgrading-from-major-version-3-to-4)\n- [Starting and Stopping](#starting-and-stopping)\n - [Stopping](#stopping)\n - [Starting](#starting)\n- [Uninstall](#uninstall)\n- [User Interfaces](#user-interfaces)\n - [Search UI](#search-ui)\n - [Report Engine UI](#report-engine-ui)\n - [The Admin Dashboard](#the-admin-dashboard)\n - [The Management Console](#the-management-console)\n - [The Authority Service Admin Console](#the-authority-service-admin-console)\n - [The Solr Dashboard](#the-solr-dashboard)\n - [The Grafana Dashboard](#the-grafana-dashboard)\n - [The PostgreSQL pgAdmin Dashboard](#the-postgresql-pgadmin-dashboard)\n - [Mongo Express](#mongo-express)\n- [Integrations](#integrations)\n - [Search Bar in Web Applications](#search-bar-in-web-applications)\n - [Full Integration in Web Applications](#full-integration-in-web-applications)\n - [Microsoft Copilot](#microsoft-copilot)\n- [Known Issues](#known-issues)\n - [Losing Connection to Docker Daemon](#losing-connection-to-docker-daemon)\n - [Saga Not Starting Due to docker-compose Upgrade Failure](#saga-not-starting-due-to-docker-compose-upgrade-failure)\n - [Issue When Uninstalling Major Version 3 Connectors](#issue-when-uninstalling-major-version-3-connectors)\n - [Duplicated Client Mappers in Authority Service](#duplicated-client-mappers-in-authority-service)\n - [Firewall Blocks Communication between Containers](#firewall-blocks-communication-between-containers)\n - [gMSA Must Have Access to the TGGAU Attribute on User Account Objects](#gmsa-must-have-access-to-the-tggau-attribute-on-user-account-objects)\n\n# Introduction\n\nLocator is an enterprise search engine able to retrieve and index a large variety of office type documents and make these searchable.\n\nThe Locator product runs on top of the Saga Platform. The name Saga may thus sometimes appear where one otherwise would expect the name Locator.\n\nCompared to Locator 2.x, the 6.4.0 version of Locator has many new customer facing features. However, the most significant change is that Locator 6.x, as all versions since 3.x, is running on top of Docker.\n\n## Target Audience\n\nThis guide is directed towards system administrators that are to install Locator 6.4.0.\n\n## Architectural Overview\n\nFor an architectural overview, consult [Saga Architectural Overview](https://ayfie-dev.atlassian.net/wiki/spaces/SAGA/pages/2180251662/Ayfie+Saga+Architectural+Overview)\n\n## Limitations\n\nNot all features and use cases supported in 2.x are yet supported. Locator 6.4.0 only supports...\n\n- ...new installations and upgrades from 3.x and later versions (consult [Migration from Version 2.x to the Latest](https://ayfie-dev.atlassian.net/wiki/spaces/SAGA/pages/3312254977/Migration+from+Version+2.x+to+the+Latest) for how to manually migrate to the new platform)\n- ...single node installations.\n- ...online installations. It is not possible to neither install nor restart Locator if it is not online.\n- ...some of the many connectors that were supported in 2.11 (but new connectors are released all the time).\n- ...the UI integrations listed in section [Integrations](#integrations).\n- ...default Solr configuration, no custom Solr *schema* or *solrconfig* overrides.\n\n## Browser Support\n\nLocator works with all up to date modern browsers.\n\nMicrosoft IE is not supported.\n\n## End User License Agreement\n\nBy installing the software one is accepting the [End User License Agreement](https://www.ayfie.com/hubfs/terms/eula.pdf).\n\n# Prerequisites\n\n## Gateway Hostname\n\nThe first prerequisite to complete is to decide on a Gateway Hostname as some prerequisites depend on knowing the Gateway Hostname.\n\nThe Gateway Hostname is the FQDN used to access Saga applications:\n* https://\\/search\n* https://\\/report-engine\n\nThese prerequisites/configurations depend on knowing the Gateway Hostname:\n* [HTTPS](#https)\n* [gMSA Account](#gmsa-account)\n* [User Authentication](#user-authentication)\n\nThe installer will by default use the host server's FQDN as the Gateway Hostname. One should however change the Gateway Hostname to some other FQDN with a CNAME, an ALIAS or an A Record type DNS entry, to facilitate future OS migrations.\n\n## Hardware Requirements\n\nLocator has the following resource consumption characteristics:\n- Indexing and search are disk I/O intensive operations that require a fast disk. It is recommended using an NVMe SSD disk for the D:\\ drive where Locator is installed.\n- Data conversion (OCR in particular), entity extraction (Lingo) and indexing are all CPU intensive operations that will benefit greatly from fast CPUs.\n- Data retrieved from the data sources and converted to a textual format is first stored in an internal (PostgreSQL) or external (SQL Server) database before being indexed and becoming part of the searchable index (Solr). This means that Locator stores retrieved data twice, first in the database and then in the index. The use of an internal vs. an external database will thus have a significant impact on how much disk space that is required by the Locator host. The table below assumes the use of an internal PostgreSQL database and the amount of required disk space will be significantly less if one instead uses an external SQL Server database.\n- Locator is multi-threaded with many memory demanding processes running in parallel. Having enough memory is therefore essential.\n\n Initial indexing is more resource demanding than later operations. The table below aims at covering the peak resource demand.\n\nThe C: drive, that holds both the Windows OS and the Docker framework, must have a minimum size of 150 GB. The Locator application should be installed on a separate drive (normally the D: drive). Its minimum disk size requirement is given by the Locator Drive Size column in the table below.\n\n|Documents |CPU Speed|CPU Cores |RAM |Locator Drive Size|\n|:-----------------------:|:-------:|:----------:|:------:|:------------------------:|\n|0-10,000 | ~2 GHz| 4| 16 GB| 50 GB|\n|10,000-100,000 | ~2.5 GHz| 4| 16 GB| 100 GB|\n|100,000-500,000 | ~3 GHz| 4| 24 GB| 100-250 GB|\n|500,000-2,000,000 | 3+ GHz| 8| 40 GB| 250-500 GB|\n|2,000,000-10,000,000 | 3+ GHz| 16| 64 GB| 500-1000 GB|\n|>10,000,000 | 3+ GHz| 16| 88+ GB| 1+ TB|\n\nBy default Locator operates with 1 Lingo thread. Each Lingo thread has a cost of up to 8 GB of RAM. If one were to adjust the number of these threads or adjust the memory limit on a thread (or disables Lingo altogether), the resulting change in RAM usage should be taken into consideration.\n\n## Operating System\n\nSaga currently supports two operating systems, Windows Server 2019 and Windows Server 2022.\n\n|Supported Operating System |Microsoft Mainstream End Date|Saga End Date |\n|:-------------------------:|:---------------------------:|:----------------:|\n|Windows Server 2019 | Jan 9, 2024 | To be determined |\n|Windows Server 2022 | Oct 13, 2026 | Oct 13, 2026 |\n\nOnce the Saga End Date is reached for one's Saga installation, one needs to migrate the installation on to a server with a supported OS before being able to update to the next major version of Saga. Instructions on how to do the migration can be found in [Migration to Newer Windows Server](https://ayfie-dev.atlassian.net/wiki/spaces/SAGA/pages/3684564997/Migration+to+Newer+Windows+Server)\n\nThe required migration stem from the fact that Saga uses Windows Server containers for process isolation and the container framework is OS specific as described in [compatibility matrix](https://learn.microsoft.com/en-us/virtualization/windowscontainers/deploy-containers/version-compatibility).\n\n## Content Handler\n\nThe Content Handler is a Windows only utility, used to open some search result links in their native applications on the client. These are links referencing data retrieved by any of the connectors listed below. Without the Content Handler installed, these links will have limited opening functionality.\n* eDOCS DM\n* Exchange (on-premises version only)\n* FileServer\n* WorkSite\n\nThe Content Handler can either be downloaded by each individual user from the Locator search UI, in which case there are no prerequisites. Alternatively a system administrator can download an [MSI installer](https://nexus.ayfie.dev/repository/Raw-Hosted/contenthandler-releases/5/ContentHandler.msi) and roll the Content Handler out to all users in one operation. The system administrator can distribute the MSI installer using this command:\n ```\n msiexec /quiet /i ContentHandler.msi APPLICATIONFOLDER=\"C:\\Program Files (x86)\\ayfie\\Content Handler\"\n ```\n\nNote that the installer will install .NET Framework 4.7.2 if not already installed at the client.\n\n## Anti-Virus Programs\n\nAnti-virus programs should preferably be stopped. If that is not possible, at a very minimum all Docker and Locator related directories should be exempted. Assuming a default Docker installation and recommended Locator installation, these are the directories (include sub-directories) that should be excluded:\n- D:\\Program Files\\ayfie\\saga\n- C:\\ProgramData\\docker\n\nThere are some anti-virus programs that are completely incompatible with Locator and should not be run on the host machine under any circumstances. Here is a non-exhaustive list of such programs:\n- Trend Micro Antivirus\n- Cynet\n- WebRoot SecureAnywhere\n- BitDefender\n\n## Host Server Ports\n\nThe host server's ports 80 and 443 are used by Saga. Any other application or service using those ports (for instance IIS) will interrupt Saga and thus need to be stopped or reconfigured.\n\n## License\n\nA valid license is required to enable features and capabilities once the initial 30 day free trial period expires. Licenses are added using the [Management Console](#the-management-console).\n\nThe features that depend on the license are:\n* Search UI - New users can log in as long as the license has free user slots.\n* Index - Documents will be added to the index as long as the document volume limit is not exceeded.\n* Converter - Requires the DocFilter and OmniPage OCR capability.\n* Lingo - Requires either Lingo Standard or Lingo GDPR (PII) capability, see [Lingo](#lingo).\n* Report Engine - Requires the Report Engine capability.\n* Connectors - Each connector have their own capability. This capability is required for the connector to start.\n* Personal Assistant - Requires the Personal Assistant capability.\n* Smart Classifier - Requires the Smart Classifier capability.\n\n## HTTPS\n\nThe Search and Report Engine UIs require the use of the HTTPS protocol, To facilitate that, Locator needs to be set up with an SSL certificate. The prerequisite for this depends on how the certificate is obtained:\n\n- Received from a commercial Certificate Authority (CA) such as for instance IdenTrust, DigiCert, Sectigo, GoDaddy, etc.\n- Automatically generated by Let’s Encrypt during the Locator installation\n\nThe prerequisites in regard to the first option are:\n- two PEM formatted files, \\.crt and \\.key.\n- the \\.crt has [Gateway Hostname](#gateway-hostname) set in the Subject Alternative Name attribute. This applies even if there technically are no alternative names.\n- the \\.key file has an unencrypted private key.\n\nSee [Saga SSL Certificate Management](https://ayfie-dev.atlassian.net/wiki/spaces/SAGA/pages/2987327489/Saga+SSL+Certificate+Management) for details.\n\nThe two files are to be placed into directory _D:\\Program Files\\ayfie\\saga\\volumes\\Traefik\\certs_ (the given path assumes the recommended install directory) during installation.\n\nThe prerequisites in regard to the second option of using Let’s Encrypt's are all network related:\n- One must be using an approved public Top Level Domain (TLD)\n- The Locator server must be exposed to the public Internet\n- Port 80 of the Locator host's firewall must be open\n- There must be a DNS A record entry for the Locator host FQDN and its public IP\n\n## gMSA Account\n\nA *group Managed Service Account (gMSA)* is required if **any** of the following is true:\n- Saga is set up with a [Microsoft SQL Server](#microsoft-sql-server) database.\n- Saga is set up with one or more connectors that access resources over the Windows-based network (for instance by reading files from the disk of another server).\n- Authority service is set up with [Active Directory](#active-directory) user authentication.\n- Authority service is set up with [Azure Active Directory](#azure-active-directory) user authentication and the [Saga AD AAD Sync](#saga) setting is enabled in the Saga install script.\n\nFor instructions on how to create the gMSA account, see [Create gMSA Account](https://ayfie-dev.atlassian.net/wiki/spaces/SAGA/pages/3343745025/Create+gMSA+Account)\n\n## User Authentication\n\nOnce Saga has been installed one needs to configure the Authority Service (Keycloak) with the authentication method that is to be used as instructed in the *Post-Install Configuration* section further down. The two options are Active Directory and Azure Active Directory, each option with a different set of prerequisites (see the two sections).\n\n### Deciding Authority Service Authentication Method\n\nThe recommended authentication method to use in the Authority Service is Azure Active Directory for the following reasons:\n- Easier to configure.\n- Enables 2 Factor Authentication (2FA).\n\nHowever, it is not always possible to use the recommended authentication method as some connectors are not compatible with that approach. One should for that reason consult the [User Authentication Method Matrix](https://ayfie-dev.atlassian.net/wiki/spaces/SAGA/pages/3327950849/User+Authentication+Method+Matrix) before determining which authentication method to configure.\n\n### Active Directory Prerequisites\n\nThese are the Active Directory prerequisites:\n- The LDAP connection URL\n- The full distinguished name (DN) of the LDAP tree where users are stored.\n- An Active Directory service account named *svcSagaKeycloak* with Domain User permissions\n- The service account Bind DN string\n\nSee the Prerequisites section of [Configure Active Directory user federation in Authority Service](https://ayfie-dev.atlassian.net/wiki/spaces/SAGA/pages/2893578241/Configure+Active+Directory+user+federation+in+Authority+Service) for more details.\n\n### Azure Active Directory Prerequisites\n\nThese are the Azure Active Directory prerequisites:\n- An Azure Active Directory client ID\n- The corresponding Azure Active Directory client secret\n- The OpenID Connect metadata document URL\n\nSee the Prerequisites section of [Configure Azure Active Directory identity provider in Authority Service](https://ayfie-dev.atlassian.net/wiki/spaces/SAGA/pages/2893578248/Configure+Azure+Active+Directory+identity+provider+in+Authority+Service) for more details.\n\n## Microsoft SQL Server\n\nAll data retrieved by the connectors is converted to text and stored in a database before being indexed. Saga has a built-in PostgreSQL database that is used by default. However, an external Microsoft SQL Server can be used instead. The pros and cons of using either of the two options are discussed in [Built in PostgreSQL vs. External Microsoft SQL Server](https://ayfie-dev.atlassian.net/wiki/spaces/SAGA/pages/2941812766/Built-in+PostgreSQL+vs.+External+Microsoft+SQL+Server).\n\nIf one opts for using an external Microsoft SQL Server database, see [Configure with an external Microsoft SQL Database Server](https://ayfie-dev.atlassian.net/wiki/spaces/SAGA/pages/2374336517/Configure+with+an+external+Microsoft+SQL+Database+Server) for how to prepare the database before installing Saga.\n\nIn addition, as the [Management Console](#the-management-console) depends on the database for it functions, users that are to operate it must be assigned the *db_datareader* and *db_datawriter* roles for the Locator database.\n\n## Firewall Openings\n\nIt is not possible to install and operate Locator without access to the Internet over port 443 (TCP protocol). It is however possible to reduce the external access from the host to only sites being used by Locator. Consult the full list of required [firewall openings](https://ayfie-dev.atlassian.net/wiki/spaces/SAGA/pages/3075112967/Ayfie+Saga+Firewall+Openings).\n\n## IP Blocking\n\nIt is not possible to do IP blocking if one uses an SSL certificate from Let's Encrypt.\n\n## Prerequisites for Optional Features\n\nThe following optional features have their own required prerequisites:\n- **Connectors** - Each individual connector has its own set of prerequisites that can be looked up at [Connector Data Sheets](https://ayfie-dev.atlassian.net/wiki/spaces/SAGA/pages/2928246816/Ayfie+Connector+Data+Sheets).\n- **Personal Assistant** - See [Configure Personal Assistant](https://ayfie-dev.atlassian.net/wiki/spaces/SAGA/pages/3410165780/Configure+Personal+Assistant).\n- **Smart Classifier** - See [Smart Classifier ML Install Guide](https://ayfie-dev.atlassian.net/wiki/spaces/SAGA/pages/3228499969/Ayfie+Smart+Classifier+ML+Install+Guide).\n\n# Installing\n\nNew versions of the Saga platform are released using the continuous delivery approach. The Saga platform is versioned using semantic versioning. When a new minor versions is released, running the saga.ps1 script will automatically result in an upgrade to that new version. When a new major version is released, a new version of saga.ps1 must be downloaded to replace the existing saga.ps1, and be executed according to the [upgrade instructions](#major-version-upgrades) given for that new major version.\n\n## Installation and Restart Time\n\nLocator runs as a set of Docker containers that are instantiations of Docker images that are downloaded the first time Locator starts up. The time to download these images will vary depending on the amount of changes, and is likely to take some 15-20 minutes the first time (and \"hang\" for a few minutes after reporting that all images have been downloaded).\n\n## Installation Drives and Directories\n\nLocator is a Docker based application and Locator installations consist of two parts, the Docker framework and the Locator application running on top of it. The Docker framework can only be installed on the C: drive (it can later be moved to another drive but that is outside the scope of this documentation). The Locator application should be installed on a different drive than the Windows OS. The D: drive is what is normally used. The minimum size of the two drives is given in [Hardware Requirements](#hardware-requirements).\n\nAny directory can be used to house the Locator application. However, the convention is to use the same directory structure as used by most other Windows installations:\n\n```\nD:\\Program Files\\ayfie\\saga\n```\n\nIn the rest of this documentation we will assume that the directory given above is the one used for the installation.\n\n## Running the Install Script\n\nTo install Locator, run the command lines shown below one by one from within an elevated PowerShell shell (do **not** run them from within PowerShell ISE):\n\n```\n> mkdir \"D:\\Program Files\\ayfie\\saga\"\n> cd \"D:\\Program Files\\ayfie\\saga\"\n> Invoke-WebRequest -Uri https://nexus.ayfie.dev/repository/Raw-Hosted/locator-releases/6/saga.ps1 -OutFile saga.ps1\n> Get-ChildItem saga.ps1 | Unblock-File\n> .\\saga.ps1\n```\n\nAbove we see the install directory being entered, the *saga.ps1* installation script being downloaded, digitally signed and then finally started.\n\nOne will be prompted to accept the [End User License Agreement](https://www.ayfie.com/hubfs/terms/eula.pdf) to which one has to respond *Y* in order to continue:\n\n```\nThe Saga End User License Agreement (EULA) is found at: https://www.ayfie.com/hubfs/terms/eula.pdf\nDo you accept the EULA? [Y/n]:\n```\n\nIf Docker is not already installed, then the server will be restarted upon the install script having installed it. Run the script all over again once the server is back up.\n\nA successful installation will have the installer script terminate by showing the graphic below:\n\n```___\n / ___/____ _____ _____ _\n \\__ \\/ __ `/ __ `/ __ `/ Welcome to Saga\n ___/ / /_/ / /_/ / /_/ / Start time: YYYY-MM-DD HH:MM:SS\n/____/\\__,_/\\__, /\\__,_/\n /____/\n```\n\nRunning the *docker ps* command should show *healthy* (and not *starting* or *unhealthy*) in the *STATUS* column (if the container has that type of information at all).\n\n## The Install Script Menu\n\nThe *saga.ps1* script is not only used as an install script. It can also be used for changing some of the Locator configurations at any time after the installation. Only the first time the script is run will the menu appear automatically. However, at any later time one can use the *-Configure* flag for the menu to be shown:\n\n```\n> .\\saga.ps1 -Configure\n```\n\nAll configurations performed using the menu are persisted in the file *D:\\Program Files\\ayfie\\saga\\docker\\custom.env*.\n\nBelow we see the different sections of the installation/configuration menu displayed during installation. Looking at the menu further below, notice how the first word of each line defines the various sections:\n\n- **Saga** - The Locator solution runs on top of the Saga Platform. In this section one finds parameters that does not naturally fit into any of the other categories below.\n- **Database** - Settings related to the database used by Locator to store configurations and retrieved and converted data that is to be indexed.\n- **Gateway** - Settings related to the hostname and HTTPS that is required by the UIs.\n- **Languages** - Settings related to language functionality.\n- **Solr** - Settings related to the search index.\n- **Lingo** - Settings related to the linguistic functionality.\n- **Report Engine** - Settings related to the Report Engine.\n- **Metrics** - Settings related to the collection and display of Locator performance and health data.\n- **Personal Assistant** - Settings related to the Personal Assistant functionality.\n- **Smart Classifier** - Settings related to the Smart Classifier functionality.\n- **Advanced** - Advanced Locator configuration menu, changes in advanced setting should only be done after contacting support.\n\nIn the following sections we will cover these menu sections one by one.\n\nThe full menu looks like this:\n\n```\nYour customized configuration values. Please choose from the list below to change.\n\n Saga AD Service Account:\n Saga AD AAD Sync: false\n Saga Auto Restart\n Saga Branding: ayfie\n Saga PreReleaseTag:\n Database Type: POSTGRES\n Database Server: ayfie-saga-db\n Database Port: 5432\n Database Name: Locator\n Gateway Host Name:\n Gateway Certificate Name:\n Gateway Certificates Resolver:\n Gateway Acme Email:\n Languages Converter: en;nb\n Languages Index: en;nb\n Solr Java Memory Setting: -Xms4g -Xmx4g\n Lingo Disable: False\n Lingo Extraction Image Id: nb\n Lingo Pipeline Pool Size: 2\n Report Engine Disable: True\n Metrics Disable: False\n Personal Assistant\n Smart Classifier\n Advanced\n == Exit ==\n\n```\n\nThe values we see at the end of each line are default settings. A few are blank and some of those have to be set. The script will keep returning to the menu upon exiting it until all required fields are set.\n\nUse the arrow keys to move up and down to the field that one wants to set and then press enter to edit, or as in some cases, toggle the field value.\n\n### Saga\n\n- **Saga AD Service Account:** Enter the gMSA account name with a dollar sign tagged to the end of it (corresponds to the SAM account name). That is, if the account name is *locator* as in our example above, then enter it as *locator$*. See section [gMSA Account](#gmsa-account) for further details.\n- **Saga AD AAD Sync:** Determines whether or not Active Directory authorization will be performed when the Authority Service is set up with Azure Active Directory. Set it to *true* if users are synchronized by [Azure AD Connect](https://learn.microsoft.com/en-us/azure/active-directory/hybrid/whatis-azure-ad-connect) or otherwise having matching *userPrincipalName* properties across Active Directory and Azure Active Directory; otherwise set it to *false*.\n- **Saga Auto Restart** - Menu used to set up automatic Locator restart and thus automatic upgrade to the latest minor or patch version.\n - **Daily/weekly** - Determines the time unit of the next input field\n - **Days/weeks between restarts** - Number of days/weeks between restarts\n - **Time of restart** - The time of the restart given as HH:MM\n - **Restart days** - Set which days to restart (appears only if \"weekly\" has been chosen above)\n - **User password** - The password of the user running the installer is required for later running the scheduled restart script\n - **== Remove ==** - Removes any existing restart schedule\n - **== Save ==** - Saves the schedule and then exits\n - **== Back ==** - Exits without saving\n- **Saga Branding:** Set to *custom* to change the branding theme. The default theme is *ayfie*. The changed setting must be accompanied by the execution of the steps described in [Custom Branding](#custom-branding). If these steps are carried out afterwards, a restart of Saga is required.\n- **Saga PreReleaseTag:** This parameter is for internal use leading up to a new release.\n\n### Database\n\nAll data retrieved by the Locator's connectors is stored in a database before being indexed. Locator has a built-in PostgreSQL database and the default settings relate to that database. By changing the settings one can instead use an external Microsoft SQL Server database.\n\n- **Database Type:** The type of database, select POSTGRES or MSSQL from the drop down.\n- **Database Server:** If POSTGRES, *ayfie-saga-db*. If MSSQL and a named database instance, set to *\\\\\\*. If not named, set to the FQDN of the databases's host server.\n- **Database Port:** The port that the database can be reached on. Default port for Postgres is 5432. If MSSQL and a named database instance, set to 0. Otherwise, set to the port number used.\n- **Database Name:** The name of the database.\n\n### Gateway\n\nThe table below shows the field values to be set based on the type of certificate one is using (see section [HTTPS](#https) for further details):\n\n| | Certificate Authority provided | Let's Encrypt generated |\n|:-----------------------------------|:--------------------------------------|:---------------------------------------|\n| **Gateway Host Name:** | [Gateway Hostname](#gateway-hostname) | [Gateway Hostname](#gateway-hostname) |\n| **Gateway Certificate Name:** | the \\ of \\.crt | |\n| **Gateway Certificates Resolver:** | | \"letsencrypt\" |\n| **Gateway Acme Email:** | | contact email |\n\nA quoted value means that it is to be used as-is (but without the quotes). Empty fields means to leave the menu field empty.\n\n### Languages\nIt's recommended that the same set of languages are configured for both Converter and Index Languages. The following language codes are supported: *bg* (Bulgarian), *cs* (Czech), *da* (Danish), *nl* (Dutch), *en* (English), *fi* (Finnish), *fr* (French), *de* (German), *it* (Italian), *nb* (Norwegian), *pl* (Polish), *pt* (Portuguese), *ru* (Russian), *es* (Spanish), *sv* (Swedish) and *uk* (Ukrainian).\n\nChanges to the language configuration will only apply to documents that are updated after the change. A full reindex is thus recommended when changing *Languages Index*. A full refetch can be considered when changing *Languages Converter*.\n\n- **Languages Converter:** The converter operates with language specific lists of characters that define the set of characters that can be detected during OCR. Specifying the languages of the data set will thus improve the accuracy of the OCR process.\n\n- **Languages Index:** The (Solr) index uses the configured languages to decide which languages that can be detected. A document's detected language is the bases for further linguistics analyses upon it such as stop word filters, stemming, etc.\n\n### Solr\n\nSolr is the actual search engine within Locator.\n\n- **Solr Java Memory Setting:** In general, Java Virtual Machines (JVM) are typically not good at freeing up memory once it has allocated it. For that reason it is important that one set the Solr Java Memory limit low enough to avoid other components from running out of memory, while at the same ensuring that Solr has enough memory. The default value is 4 GB which is only enough for small indexes with relative few documents. The suggested memory limits in the table below are based on the number of indexed documents. These limits should be considered a rule of thumb and increased further if Solr were to run out of memory.\n\n |Documents | Solr Java Memory |\n |:-----------------------:|:----------------:|\n |0-100,000 | 2 GB|\n |100,000-500,000 | 4 GB|\n |500,000-2,000,000 | 8 GB|\n |2,000,000-10,000,000 | 16 GB|\n |>10,000,000 | 16+ GB|\n\n### Lingo\n\nLingo is a Natural Language Processing (NLP) component that extracts two types of entities from the incoming data, Personally Identifiable Information (PII) like passport numbers, social security numbers, driver's license number's, etc., and more general and less sensitive entities such as dates, names of persons, locations, organizations, etc. There are two types of images for these two types of entity extraction, the GDPR (PII) extraction image and the standard extraction images. Only one extraction image can be used at any given time. The Report Engine requires the GDPR extraction image. If one is not to use the Report Engine, then select a standard extraction image based on the predominant language of the data set.\n\n- **Lingo Disabled:** This parameter is the master switch. If toggled to *True*, Lingo will be disabled. By default the value is *False*.\n- **Lingo Extraction Image Id:** This parameter determines which Lingo extraction image to be used. That can be one of the standard extraction images: da (Danish), en (English), fr (French), de (German), it (Italian), nb (Norwegian), pl (Polish), pt (Portuguese), es (Spanish) and sv (Swedish), or the GDPR extraction image: PII. The language in parentheses, like English in *PII (English)*, indicates the language dependent date format to be used during extraction. Note that if the extraction image identifier is changed after install time, a full re-index would have to be performed.\n- **Lingo Pipeline Pool Size:** The pipeline pool size is the maximum number of pipelines that Lingo may use at any given time. A pipeline corresponds to a processing thread. Each pipeline normally consumes about 2 GB of memory and never more than the memory threshold explained next.\n\n### Report Engine\n\nThe purpose of the report engine is to create reports, typically data compliance reports that identifies the presence of any sensitive information within the data that has been indexed. For more information on the report engine, consult [this article](https://ayfie-dev.atlassian.net/wiki/spaces/SAGA/pages/2928640017/What+is+Ayfie+Supervisor).\n\n- **Report Engine Disable** If set to *True*, the Report Engine will be disabled. By default the value is *True*.\n\n### Metrics\n\nLocator provides internal performance and health metrics via the Grafana Dashboard.\n\n- **Metrics Disabled:** True by default. Toggle to enable.\n\n### Personal Assistant\nPersonal Assistant allows users to chat with large language models and to interrogate documents using these same models. To enable the Personal Assistant, three models have to be configured in Azure, consult [Configure Personal Assistant](https://ayfie-dev.atlassian.net/wiki/spaces/SAGA/pages/3410165780/Configure+Personal+Assistant) for details.\n\nThe three models that must be configured are:\n\n- **Main Model** - The default model used for chat.\n- **High Quality Model** - The high quality model used for chat.\n- **Embeddings Model** - The model for creating a numeric representation of the text. Only *text-embedding-ada-002* is currently supported.\n\nIn addition one may also configure this model:\n- **High Quality Plus Model** - The high quality plus model used for chat.\n\nIn the Personal Assistant menu one needs to configure the following:\n\n- **Personal Assistant Mode:** Defines the criteria that is used to determine which users that will have access to which flavor of the Personal Assistant feature. These are the three alternatives:\n - **off** - the default value. The Personal Assistant feature is disabled for everyone.\n - **limited** - enables the Personal Assistant only for users with the *search.personal_assistant.premium* role, see [Managing Users and Roles](#managing-users-and-roles).\n - **full** - allows all users access to the Personal Assistant.\n- **Default Model:** The default model in the model dropdown in the UI. These are the three alternatives values that can be used as the default:\n - **main** - the default value. Enables the Main model as the default model.\n - **hq** - enables the High Quality model as the default model.\n - **hqplus** - enables the High Quality Plus model as the default model.\n- **Main Model Deployment:** The name of the main model deployment in Azure.\n- **Main Model Display Name: GPT-3.5** The display name of the main model in the UI.\n- **Main Model API Address:** The API Address of the main model deployment in Azure.\n- **Main Model API Key:** The API Key of the main model deployment in Azure.\n- **Main Model Token Size:** The maximum number of input tokens to be used with the main model. A model has a maximum total number of tokens that can be used across the input and the output. The input is made up of questions and uploaded documents and only what is not used in the input can be used for the output. It is thus important to select a value within the overall capacity of the model that still leaves room for the output. The *Recommended Token Size* in the table below is the recommendation for such a number. It is also worth noting that one is billed by the total number of tokens used in the input, so reducing the token size will reduce the operational cost of the feature.\n | Model | Model Version | Max Tokens | Recommended Token Size |\n |:---------------:|:---------------:|:----------:|:----------------------:|\n |gpt-4o-mini |2024-07-18 | 128.000| 15000|\n |gpt-4 |turbo-2024-04-09 | 128.000| 30000|\n |gpt-4o |2024-05-13 | 128.000| 30000|\n- **Main Model Description:** The description of the main model in the UI.\n- **High Quality Model Deployment:** The name of the high quality model deployment in Azure.\n- **High Quality Model Display Name: GPT-4** The display name of the high quality model in the UI.\n- **High Quality API Address:** The API Address of the high quality model deployment in Azure.\n- **High Quality API Key:** The API Key of the high quality model deployment in Azure.\n- **High Quality Model Description:** The description of the high quality model in the UI.\n- **High Quality Token Size:** The maximum number of input tokens of the high quality model deployment in Azure. The same information given regarding the Main Model Token Size above applies for this one as well.\n- **High Quality Plus Model Deployment:** The name of the high quality plus model deployment in Azure.\n- **High Quality Plus Model Display Name:** The display name of the high quality plus model in the UI.\n- **High Quality Plus API Address:** The API Address of the high quality plus model deployment in Azure.\n- **High Quality Plus API Key:** The API Key of the high quality plus model deployment in Azure.\n- **High Quality Plus Token Size:** The maximum number of input tokens of the high quality plus model deployment in Azure. The same information given regarding the Main Model Token Size above applies for this one as well.\n- **High Quality Plus Description:** The description of the high quality plus model in the UI.\n- **Embeddings Model Deployment: text-embedding-ada-002** The name of the embeddings model deployment in Azure.\n- **Embeddings Model API Address:** The API Address of the embeddings model deployment in Azure.\n- **Embeddings Model API Key:** The API Key of the embeddings model deployment in Azure.\n- **Data Retention** Settings related to Personal Assistant Data Retention.\n - **Data Retention Policy Disable: true** Set to *False* to enable the data retention policy for permanent files.\n - **Data Retention Expiration Time in Days: 30** After how many days inactive permanent files will be deleted\n - **Data Retention File Inactive Time in Days: 20** After how many days a permanent file is marked as inactive\n - **Data Expiration Time In Seconds: 360000** All temporary data older than the expiration time will be removed when starting new session. The default is 360000 (10 hours).\n\n### Smart Classifier\n\nThe Smart Classifier is a feature for users to create, train and activate machine learning models to be used on sets of indexed documents. The Smart Classifier feature requires the Smart Classifier ML services, consult [Smart Classifier ML Install Guide](https://ayfie-dev.atlassian.net/wiki/spaces/SAGA/pages/3228499969/Ayfie+Smart+Classifier+ML+Install+Guide).\n\n- **Smart Classifier Disable: True** Set to *False* to enable the Smart Classifier feature.\n- **Smart Classifier Worker Count: 4** Kafka Consumer count used by Smart Classifier.\n- **Smart Classifier ML Service Address:** The FQDN used to access the Smart Classifier ML services, https://\\, where Gateway Hostname is set in the Smart Classifier ML installer.\n- **Smart Classifier ML Basic Auth Password:** The *Gateway Basic Auth Password* set in the Smart Classifier ML installer.\n\nThe Smart Classifier feature is only accessible by users with the appropriate role, see [Managing Users and Roles](#managing-users-and-roles).\n\n# Post-Install Configuration\n\n## Configuring the Authority Service\n\nThe Authority Service is a Saga user authentication and management solution built on the Keycloak platform.\n\nAdministrative activities are performed in the Authority Service Admin Console. See [The Authority Service Admin Console](#the-authority-service-admin-console) for details on how to log in.\n\nThe Authority Service authenticates and authorizes users across all products in the Saga platform. During authentication, the Authority Service looks the user up in its internal user database. If the user is not to be found there, the Authority Service will then search for the user across all user storage providers that it has been configured to use.\n\nThere are two types of user storage providers:\n - **Federated user databases** are user databases that Saga communicates with using the LDAP protocol. Saga itself provides the login page and then passes user credentials on to the federated user database for authentication. [Active Directory](#active-directory) is, and will remain, the only supported user database of this type.\n\n - **Identity providers** are third party user storage providers that Saga communicates with using protocols such as OpenID Connect. Login is done by Saga passing the user on to the identity provider's login page to enter the user's credentials there. [Azure Active Directory](#azure-active-directory) is currently the only identity provider supported by Saga, but others are to follow in the future.\n\nIn either case, users that are successfully authenticated are imported into the Authority Service and their user attributes are mapped based on either LDAP attributes or OpenId Connect claims, depending on the type of user storage provider. Once the user is imported into the Authority Service, one may assign additional roles to the user. See [Managing Users and Roles](#managing-users-and-roles).\n\n### Active Directory\n\nTo configure Active Directory user federation, consult [Configure Active Directory User Federation](https://ayfie-dev.atlassian.net/wiki/spaces/SAGA/pages/2893578241/Configure+Active+Directory+user+federation+in+Authority+Service).\n\n ### Azure Active Directory\n\n To configure Azure Active Directory identity provider, consult [Configure Azure Active Directory Identity Provider](https://ayfie-dev.atlassian.net/wiki/spaces/SAGA/pages/2893578248/Configure+Azure+Active+Directory+identity+provider+in+Authority+Service).\n\n### Managing Users and Roles\n\nOnce a user is imported into the Authority Service's internal user database, the user can be granted additional roles in the Saga platform by the administrator. By default the user will be allowed to use the search UI with the default feature set. Some features and products require additional role(s) to be granted to the user.\n\nTo grant a role to a specific user do the following:\n1. Log in to the [Authority Service Admin Console](#the-authority-service-admin-console) as the *saga_admin* user.\n2. Click Users in the left menu bar.\n3. Search for a specific user.\n4. Select the user to grant a role.\n5. Go to Role Mappings tab.\n5. Click Assign Role.\n6. In filter drop-down, select *Filter by clients*.\n7. Search for *saga_implicit_client*.\n7. Grant the appropriate role to the user.\n\nThe available Locator roles are:\n- **search.public_tags.assign** - Role for assigning and unassigning public tags to documents in the search result.\n- **search.public_tags.admin** - Role for creating and deleting public tags (also includes assigning and unassigning them).\n- **search.smart-classifier** - Role required to manage Smart Classifiers.\n- **search.personal_assistant.premium** - Role required to get the premium Personal Assistant features such as the high quality model.\n\nThe available Report Engine roles are:\n- **notification.admin** - Composite role that covers all notification roles.\n- **notification.read** - Role required for viewing notification configuration.\n- **notification.write_email** - Role required for sending emails.\n- **notification.write_smtp_configuration** - Role required for configuring SMTP.\n- **report_engine.create_report** - Role required for creating reports.\n- **report_engine.delete_report** - Role required for deleting reports.\n- **report_engine.export_report** - Role required for exporting reports\n- **report_engine.admin** - Composite role that covers all report_engine roles.\n- **report_engine.read** - Role required for viewing reports.\n- **report_engine.write_dashboard** - Role required for configuring dashboards.\n- **scheduler.admin** - Composite role that covers all scheduler roles.\n- **scheduler.create** - Role for creating schedules.\n- **scheduler.delete** - Role for deleting schedules.\n- **scheduler.pause** - Role for pausing schedules.\n- **scheduler.read** - Role for viewing schedules.\n\n## Connector Management\n\n### Installing Connectors\n\nTo install a connector, do the following:\n\n- Find the connector's folder in the list of folders at https://nexus.ayfie.dev/#browse/browse:connector-installer.\n- Open the highest numbered 6.x.x sub-folder in the connector's folder to access the zip file containing the latest connector installer for Locator 6.4.0.\n- Double click the path in the window that now has opened up to the right of the folder tree.\n- Download the connector zip file as-is (remain zipped) to directory D:\\Program Files\\ayfie\\saga\\plugins.\n\nThe connector will now be automatically installed once/if Locator is up and running.\n\n### Configuring Connectors\nTo configure a connector, do the following:\n- Open the [Management Console](#the-management-console)\n- Click *Connections* and then the connector one is to configure\n- Click *Add New Connection* and run through the wizard.\n\nConsult [Connector Data Sheets](https://ayfie-dev.atlassian.net/wiki/spaces/SAGA/pages/2928246816/Ayfie+Connector+Data+Sheets) for more details on how to configure each connector.\n\n### Upgrading Connectors\n\nConnectors are automatically updated upon restart of Saga if a newer version within the same major version exists.\n\n### Uninstalling Connectors\n\nTo uninstall a connector, do the following:\n\n- Navigate to directory *D:\\Program Files\\ayfie\\saga\\plugins*\n- Copy the connector folder to *D:\\Program Files\\ayfie\\saga\\plugins\\delete*\n- Wait for the connector folder to disappear from both *D:\\Program Files\\ayfie\\saga\\plugins\\delete* and *D:\\Program Files\\ayfie\\saga\\plugins*\n\nIf one is uninstalling a 3.x connector, please also see this [known issue](#issue-when-uninstalling-major-version-3-connectors).\n\n### Secondary User Authentication\n\nUsers are authorized across the [user authentication](#user-authentication) and secondary user authentication. Authorization gathers the users security identifiers, that are used to determine which search hits the user has access to. If all configured connectors are using the user authentication configured in the Authority Service, no secondary user authentication is required. If a configured connector uses some other user authentication, the user will be asked to provide credentials after login. Secondary user authentication is registered behind the scenes when connectors are installed. Consult Authentication and Identification in the [Connector Data Sheets](https://ayfie-dev.atlassian.net/wiki/spaces/SAGA/pages/2928246816/Ayfie+Connector+Data+Sheets) to determine the required set of user authentication.\n\n## Custom Branding\n\nIt is possible to divert from the default *ayfie* branding theme and do custom branding for the following components:\n- The Search UI\n- The Authority Service (login page)\n- The Chat UI (Personal Assistant)\n\n**Branding the Search UI**\n\nPerform the following steps:\n1. In *D:\\Program Files\\ayfie\\saga\\volumes\\search-ui\\branding\\custom* (the path assumes recommended installation path), rename *brand.config.example.json* to *brand.config.json*.\n2. In *D:\\Program Files\\ayfie\\saga\\volumes\\search-ui\\branding\\custom*, rename *styles.example.css* to *styles.css*.\n3. Add a *favicon.ico* to *D:\\Program Files\\ayfie\\saga\\volumes\\search-ui\\branding\\custom*.\n4. Add a *logo.svg* to *D:\\Program Files\\ayfie\\saga\\volumes\\search-ui\\branding\\custom (one can change the file name by changing the value of the *logoPath* variable in file *brand.config.json*. SVG is the recommended image format to use due to its ability to scale. However, other image formats can also be used.)\n5. In the *custom* folder, do any of the following optional steps to customize the branding:\n - Adjust the color values in file *styles.css*.\n - Change the value of *productName* in file *brand.config.json*.\n\nFor the changes to take effect, restart Saga with `stop-saga.ps1` followed by `saga.ps1 -configure`. The latter will bring up the install menu in which one is to set *Saga Branding* to *custom*.\n\n**Branding the Login Page**\n\nIf one has configured the *Identity Provider Redirector* in the Authority Service, then one can skip branding the login page as it will not be displayed to users. See section [Configure Identity Provider Redirector](https://ayfie-dev.atlassian.net/wiki/spaces/SAGA/pages/2893578248/Configure+Azure+Active+Directory+Identity+Provider) for details.\n\nIf the login page is to be displayed, then one is free to do any of the following optional steps to customize the branding:\n- In the *D:\\Program Files\\ayfie\\saga\\volumes\\authority\\docker-entrypoint.d\\branding\\custom\\login\\resources\\css* folder, rename *styles.example.css* to *styles.css* and adjust the color values in the file.\n- Add a *logo.svg* to *D:\\Program Files\\ayfie\\saga\\volumes\\authority\\docker-entrypoint.d\\branding\\custom\\login\\resources\\img* (requires *styles.css*. One can change the file name by changing the value of the *background* variable in the *kc-header-logo* section in file *styles.css*. SVG is the recommended image format to use due to its ability to scale. However, other image formats can also be used.)\n\nFor the changes to take effect, restart Saga with `stop-saga.ps1` followed by `saga.ps1 -configure`. The latter will bring up the install menu in which one is to set *Saga Branding* to *custom*.\n\n**Branding the Chat UI**\n\nPerform the following steps:\n1. Copy the files from *D:\\Program Files\\ayfie\\saga\\volumes\\search-ui\\branding\\custom* to *D:\\Program Files\\ayfie\\saga\\volumes\\chat-ui\\branding\\custom*\n2. In the *custom* folder, do any of the following optional steps to customize the branding:\n - Adjust the color values in file *styles.css*.\n - Change the value of *productName* in file *brand.config.json*.\n\nFor the changes to take effect, restart Saga with `stop-saga.ps1` followed by `saga.ps1 -configure`. The latter will bring up the install menu in which one is to set *Saga Branding* to *custom*.\n\n## Private Certificate Authority\n\nIf Saga needs to communicate with services that are set up with SSL certificates not provided by a well-known Certificate Authority (CA) but instead by for instance the customer's own IT department, then that corresponding private CA's root certificate must be imported into the Docker containers. The situations for which one needs to import the private CA root certificate are:\n\n1. If one plans to configure [Active Directory](#active-directory) in the Authority Service using _ldaps_ and the _ldaps_ SSL certificate is issued by a private CA.\n2. If the Saga host server is configured to use a proxy for all traffic and the proxy certificate is issued by a private CA.\n\nTo import a private CA root certificate do the following:\n\n- Enter *certlm.msc* in the program search box down in the left corner (or alternatively find the tool via the *Manage Computer Certificate* option in the *Control Panel*)\n- Select *Trusted Root Certification* from the list that appears in the left pane\n- In the right window, click on *Certificates*\n- Find the Root CA from the list of certificates\n- Click on the certificate to open it and then click the *Details* tab.\n- Select *Copy To File...* and then next the *DER encoded binary X.509 (.CER)* option in the export wizard.\n- Store the file under any name but with the required .cer extension\n- Copy the file to *D:\\Program Files\\ayfie\\saga\\volumes\\certs*\n- Restart Saga\n\n## Major Version Upgrades\n\nTo upgrade to a new major version, a saga.ps1 install script for that new major version is required. Section [Running the Install Script](#running-the-install-script) describes how to obtain the installer for any given major version.\n\n### Upgrading from major version 5 to 6\n\n1. If one has enabled the Smart Classifier feature in 5.x, then upgrade the Smart Classifier ML component to 6.x on the Linux box before doing any upgrade related operations on the Windows server housing Saga. See [Ayfie Smart Classifier ML Install Guide](https://ayfie-dev.atlassian.net/wiki/spaces/SAGA/pages/3228499969/Ayfie+Smart+Classifier+ML+Install+Guide) on how to do the upgrade.\n2. Run the stop_saga.ps1 script to stop Saga.\n3. One should perform the following cleanup (the paths assumes recommended install directory):\n - Delete file *D:\\Program Files\\ayfie\\saga\\Admin\\copyexcludelist.txt*\n - Delete file *D:\\Program Files\\ayfie\\saga\\docker\\docker-compose.report-engine.override.yml*\n - Delete file *D:\\Program Files\\ayfie\\saga\\volumes\\authority\\docker-entrypoint.d\\standalone.xml*\n - Delete file *D:\\Program Files\\ayfie\\saga\\volumes\\locator\\docker-entrypoint.d\\01-locator-init.ps1*\n - Delete file *D:\\Program Files\\ayfie\\saga\\volumes\\locator\\docker-entrypoint.d\\saga-functions.psm1*\n - Delete file *D:\\Program Files\\ayfie\\saga\\volumes\\PostgreSQL\\docker-entrypoint.d\\CreateDatabase.sql*\n - Delete folder *D:\\Program Files\\ayfie\\saga\\data\\notification*\n - Delete folder *D:\\Program Files\\ayfie\\saga\\data\\scheduler*\n - Delete folder *D:\\Program Files\\ayfie\\saga\\data\\smart-refiner*\n - Remove *AYFIE_SAGA_INSTALLER_SKIP_PREREQUISITE_WINDOWS_FEATURE_CONTAINERS* variable from *D:\\Program Files\\ayfie\\saga\\docker\\custom.env* if exists.\n4. Check if Docker is installed from the DockerMsftProvider by running the following command from an elevated PowerShell shell:\n ```\n > Get-Package -Name docker -ProviderName DockerMsftProvider\n ```\n - If the command lists Docker as an installed package, uninstall Docker by running the following command from an elevated PowerShell shell:\n ```\n > Uninstall-Package -Name docker -ProviderName DockerMsftProvider\n > Uninstall-Package -Name DockerMsftProvider\n ```\n5. Download and run the 6.x version of the saga.ps1 install script, see [Running the Install Script](#running-the-install-script).\n6. The normalization framework has been deprecated in Saga 6.x. One should perform the following cleanup:\n - Open the [The Solr Dashboard](#the-solr-dashboard).\n - Go to *Collections* menu option.\n - Select the *Normalization* collection and click the *Delete collection* button.\n - Confirm the deletion by typing the name of the collection and click the *Delete* button.\n7. The index has been updated to a new major version. Perform a reindex by running the command below from an elevated PowerShell shell:\n ```\n > docker exec ayfie-locator c:/Locator/tools/via.repository.exe reindex /all\n ```\n\n**Consequences of Migration**\n- Saga 6.x ships with a new major version of Keycloak, version 22. During the upgrade a new *saga_admin* user will be created in the *Saga* realm. The new password can be found in *D:\\Program Files\\ayfie\\saga\\docker\\\\.env* (assuming recommended installation path) as the *AYFIE_SAGA_AYFIE_USER_PASSWORD* environment variable. It is recommended to later change the generated password to something else in the Authority Service Admin Console. Note that there is a new URL to log into [The Authority Service Admin Console](#the-authority-service-admin-console). The previous *admin* and other existing *master* realm users will automatically be deleted during the upgrade.\n\n### Upgrading from major version 4 to 5\n\nOne should make sure all 5.x prerequisites are in place before one starts upgrading from 4.x to 5.x.\n\n1. Uninstall all connectors, see [Uninstalling Connectors](#uninstalling-connectors). This operation will not remove any connections or indexed data.\n2. Run the stop_saga.ps1 script to stop Saga.\n3. Download and run the 5.x version of the saga.ps1 install script, see [Running the Install Script](#running-the-install-script).\n4. Install the 5.x version of the connectors that were uninstalled in step 1, see [Installing Connectors](#installing-connectors).\n5. Modern Authentication is introduced in 5.x. This requires that [User Authentication](#user-authentication) is configured in the Authority service:\n - **Scenario 1**: Report Engine is not enabled and either [Active Directory](#active-directory) or [Azure Active Directory](#azure-active-directory) must be configured.\n - **Scenario 2**: Report Engine is enabled and [Active Directory](#active-directory) or [Azure Active Directory](#azure-active-directory) is thus already configured.\n There are additional configuration steps in [Configure Active Directory user federation in Authority Service](https://ayfie-dev.atlassian.net/wiki/spaces/SAGA/pages/2893578241/Configure+Active+Directory+user+federation+in+Authority+Service) and [Configure Azure Active Directory identity provider in Authority Service](https://ayfie-dev.atlassian.net/wiki/spaces/SAGA/pages/2893578248/Configure+Azure+Active+Directory+identity+provider+in+Authority+Service) for 5.x than what there were for 4.x.\n - If [Active Directory](#active-directory) is already configured, then these are the additional configuration steps for 5.x:\n - Go to the configured User Federation in Authority Service Admin Console:\n - Add mapper for *source*.\n - Add mapper for *user*.\n - Add mapper for *upn*.\n - If [Azure Active Directory](#azure-active-directory) is already configured, then these are the additional configuration steps for 5.x:\n - Go to the registered App in Azure Active Directory:\n - Perform the Token Configuration.\n - Go to the configured Identity Provider in Authority Service Admin Console:\n - Add mapper for *source*.\n - Add mapper for *user*.\n - Add mapper for *oid*.\n - Add mapper for *upn*.\n - Add mapper for *groups*\n - Add mapper for *tid*.\n - In Default Scopes, set to *openid profile*.\n - Make sure one isn't affected by [Duplicated Client Mappers in Authority Service](#duplicated-client-mappers-in-authority-service).\n6. Configuration related to Single Sign-On has been removed from the Management Console and must now be configured in [Active Directory](#active-directory).\n7. The internal user *ayfieuser* has been removed. The license slot of this user can optionally be cleared in the Management Console.\n8. The Authority Proxy service has been removed. One should perform the following cleanup (the paths assumes recommended install directory):\n - Delete *D:\\Program Files\\ayfie\\saga\\volumes\\authority-proxy*\n - Remove *OAUTH2_PROXY_* variables from *D:\\Program Files\\ayfie\\saga\\docker\\custom.env*\n - Delete *docker-compose.authority-proxy.yml* from *D:\\Program Files\\ayfie\\saga\\docker*\n9. Delete *D:\\Program Files\\ayfie\\saga\\volumes\\authority\\docker-entrypoint.d\\saga-realm.json* if exists.\n10. If one has configured a SharePoint Online connection, one should go to the Management Console, click Edit and run the wizard for all connections. In the page for *Office 365 Domain Account Details* one needs to select the appropriate value in the *The Azure AD connector is used to obtain end user Office credentials* checkbox for ones setup. Please consult [Microsoft SharePoint Connector Data Sheet](https://ayfie-dev.atlassian.net/wiki/spaces/SAGA/pages/2937454598/Microsoft+SharePoint+Connector+Data+Sheet) for details.\n11. If one had Azure AD configured as the primary authentication realm before upgrading to 5.x, one should go to the Management Console, click Edit and run the wizard without any changes for all connections of connectors in the list below:\n - Microsoft Dynamics CRM\n - Microsoft Exchange\n - Microsoft Teams\n\nThe features listed below have been removed in 5.x. Replace them as suggested if they were in use in 4.x:\n- **Trusted Authentication** - Trusted authentication is only used by clients who have implemented a custom UI using the RestService API. Trusted authentication is in 5.x instead achieved by using Modern Authentication. See [Configuring the Authority Service](#configuring-the-authority-service).\n- **Access Control** - Access Control was a feature that could be enabled in the Management Console to restrict which users had access to the Search UI based on Active Directory groups. Access Control can in 5.x be achieved by using *Custom User LDAP Filter* when configuring [Active Directory](#active-directory) or by doing [Restrict your Azure AD app to a set of users in an Azure AD tenant](https://learn.microsoft.com/en-us/azure/active-directory/develop/howto-restrict-your-app-to-a-set-of-users) when configuring [Azure Active Directory](#azure-active-directory).\n\n### Upgrading from major version 3 to 4\n\n1. The _customer id_ and the _license key_ will be required in the last step. One may want to have the two ready before starting this procedure (a 30 days grace period is granted though).\n2. Uninstall all connectors, see [Uninstalling Connectors](#uninstalling-connectors). This operation will not remove any connections or indexed data.\n3. Run the stop_saga.ps1 script to stop Saga.\n4. Unregister the 3.x package source by running the following command from an elevated PowerShell shell:\n ```\n > Unregister-PackageSource AyfieDevNuget\n ```\n5. Download and run the 4.x version of the saga.ps1 install script, see [Running the Install Script](#running-the-install-script).\n6. Install the latest version of the connectors that were uninstalled in step 1, see [Installing Connectors](#installing-connectors).\n7. The license service has been redesigned and any license used with 3.x has to be re-added. Run the start_management_console.ps1 script, then click Operations, then License, then Add License to re-enter license info.\n\n# Starting and Stopping\n\n## Stopping\n\nUse this command to stop Locator:\n\n```\n> .\\stop-saga.ps1\n```\n\nDo not use any alternative *docker-compose* command to stop Locator as that will not give the index time to shut down in a graceful manner.\n\n## Starting\n\n```\n> .\\saga.ps1\n```\n\nThe *saga.ps1* script checks for updates, and if any compatible newer version is detected, the script will perform the upgrade before starting Locator.\n\n# Uninstall\n\nTo delete everything related to an Locator installation (including Docker itself), run these command lines one by one from within an elevated PowerShell command prompt:\n\n```\n> cd \"D:\\Program Files\\ayfie\\saga\"\n> .\\stop-saga.ps1\n> docker rmi $(docker images ayfiehub/* -qa)\n> cd ..\n> Remove-Item –path saga -recurse\n```\n\nThe command lines above will delete all Locator images (docker resources related to any still running docker application will not be effected).\n\nBy now Locator is fully uninstalled.\n\n# User Interfaces\n\n## Search UI\n\nAccessing the URL below in a browser after replacing *\\* will allow one to log in to the search UI:\n\n```\nhttps://\n```\n\nThe *Gateway Hostname* is as set during installation.\n\nThe search UI will prompt for user name and password. If integrated with AD, one may log in using any valid domain account.\n\n## Report Engine UI\n\nAccessing the URL below in a browser after replacing *\\* will allow one to log in to the Report Engine UI:\n\n```\nhttps:///report-engine\n```\n\nThe Report Engine UI will only be available if the Report Engine is enabled in the installer.\n\nTo grant user access to the Report Engine, access the Authority Service as described in [Configuring the Authority Service](#configuring-the-authority-service) and then grant roles as described in [Managing User and Roles](#managing-users-and-roles).\n\n## The Admin Dashboard\n\nAccessing the URL below in a browser running locally on the Locator server, will take one to the Locator Dashboard:\n\n```\nhttp://localhost/dashboard\n```\n\n## The Management Console\n\nRunning the script below from within an elevated PowerShell command prompt will open the Management Console:\n\n```\n> cd \"D:\\Program Files\\ayfie\\saga\"\n> .\\start-management-console.ps1\n```\n\nIf one is using a Microsoft SQL Server database, then the user that is to run the script above to start the Management Console must have been assigned the *db_datareader* and *db_datawriter* roles for the Locator database.\n\n## The Authority Service Admin Console\n\nAccessing the URL below in a browser after replacing *\\* will allow one to log in to the Authority Service Admin Console:\n\n```\nhttps:///auth/admin/saga/console\n```\n\nThe admin account's username is *saga_admin* and the generated password is found as the value of variable AYFIE_SAGA_AYFIE_USER_PASSWORD in the file *D:\\Program Files\\ayfie\\saga\\docker\\\\.env* (the path assumes recommended install directory). It is recommended that one changes the generated password. To change the password, go to the Authority Service Admin Console and enter the credentials for the administrative account. In the top right menu, click *Manage account*. Select *Signing In* in *Account Security* and update the password.\n\n## The Solr Dashboard\n\nAccessing the URL below in a browser running locally on the Locator server, will take one to the Solr Dashboard:\n\n```\nhttp://localhost/solr\n```\n\n## The Grafana Dashboard\n\nAccessing the URL below in a browser running locally on the Locator server, will take one to the Grafana Dashboard:\n\n```\nhttp://localhost/grafana\n```\n\nUse user name *admin* and password *admin* to log in and then click the Home link up in the left corner to get to the dashboards.\n\nThe Grafana Dashboard will only be available if metrics is enabled in the installer.\n\n## The PostgreSQL pgAdmin Dashboard\n\nAccessing the URL below in a browser running locally on the Locator server, will take one to the PostgreSQL pgAdmin Dashboard:\n\n```\nhttp://localhost/pgadmin\n```\n\nUse user *admin@ayfie.com* and password *Ayfi3Ru13s!* to log into the pgAdmin and then connect to the database by right clicking Servers and select Register -> Server:\n\n- In the *General* tab set the *Name* to some name, for instance *locator-db*\n- In the *Connection* tab, set the *Host name/address* field to *ayfie-saga-db* and *Username* to *postgres*\n- Click *Save*\n\nThe Locator database should now be displayed.\n\nThe PostgreSQL pgAdmin Dashboard will only be available if Postgres is set as the database type in the installer.\n\n## Mongo Express\n\nTo start mongo-express one must use the command below from within *docker* directory to start *ayfie-chat-db-ui* container:\n\n```\ndocker-compose -f docker-compose.chat-db-ui.yml up -d\n```\n\nAccessing the URL below in a browser running locally on the Locator server, will take one to the Mongo Express dashboard:\n\n```\nhttp://localhost/mongo\n```\n\nUse user *admin@ayfie.com* and password *Ayfi3Ru13s!* to log into the Mongo Express and connect to the database.\n\nThe *Chat* database should be accessible. By clicking on the database name all collections used by *ayfie-chat* should be displayed.\n\nOnce one is done using mongo-express it is recomended to stop *ayfie-chat-db-ui*, this can be done using the command below:\n\n```\ndocker-compose -f docker-compose.chat-db-ui.yml down\n```\n\nMongo-Express will only work if Personal Assistant is enabled and *ayfie-chat-db* is healthy and can be connected to.\n\n# Integrations\n\nThis section covers the ways the Saga platform and its services can be integrated into other environments.\n\n## Search Bar in Web Applications\nThe simplest way to integrate search into a web-based software is by adding an HTML form that opens the Saga provided search in a new browser tab. The following HTML code shows one way to go about doing that:\n ```\n \n ```\n\n## Full Integration in Web Applications\nThe previous section showed how to add a search bar to an existing web page. Once one performs a search from that search bar, one will be taken to the search page in a new browser tab. An alternative to that is to create a complete new search page from scratch using the RestService API. See [Ayfie Saga API Integration](https://ayfie-dev.atlassian.net/wiki/spaces/SAGA/pages/3842146425/Ayfie+Saga+API+Integration) for details on how to use the public APIs.\n\n## Microsoft Copilot\nMicrosoft Copilot is is a chatbot that is integrated in several Microsoft Office 365 products such as Teams, Outlook, PowerPoint, Words, etc. The Saga platform can be used to provide documents as context for the Copilot user prompts. To achieve this one must deploy and configure the Ayfie RAG Enabler in Microsoft Azure.\n\nThe *RAG Enabler* section of the [Saga Architectural Overview](https://ayfie-dev.atlassian.net/wiki/spaces/SAGA/pages/2180251662/Ayfie+Saga+Architectural+Overview) shows how the different parts interact.\n\n To obtain the Ayfie RAG Enabler, contact Ayfie support.\n\n# Known Issues\n\n## Losing Connection to Docker Daemon\n\nAs described in [Github issue 5044](https://github.com/docker/for-win/issues/5044), there is an issue with VMWare Tools and Docker that makes Locator lose its connection to the Docker daemon after some 10-15 minutes. The fix is to upgrade VMWare Tools to version 11.0.6 or higher.\n\n## Saga Not Starting Due to docker-compose Upgrade Failure\n\nDuring Saga startup, docker-compose updates to 1.29.2 if currently installed version is older. It is installed in \"$Env:ProgramFiles\\Docker\\\" directory. If environment variables are configured in such way, that docker-compose.exe is used from another directory, then it should be either reconfigured, or docker-compose should be manually upgraded in that directory.\n\n## Issue When Uninstalling Major Version 3 Connectors\n\nThere is a known issue when uninstalling 3.x connectors. The value of COMPOSE_FILE on the first line of the file \\docker\\plugins\\\\.env ends up with extra semicolons that for now have to be removed manually. Here is a typical example of such a case. Notice the first semicolon at the beginning of the value and the two in the middle next to each other:\n```\nCOMPOSE_FILE=;docker-compose.connector-exchange.ad.override.yml;;docker-compose.connector-worksite.ad.override.yml\n```\nSuch extra semicolons should be removed (notice how two semicolon from above have been removed below):\n```\nCOMPOSE_FILE=docker-compose.connector-exchange.ad.override.yml;docker-compose.connector-worksite.ad.override.yml\n```\nThe correction should be done after any connector has been uninstalled and before any use of stop_saga.ps1 or any new connector installation.\nThe following line in saga.ps1 or stop_saga.ps1 output, is an indication of this issue:\n```\nERROR: .FileNotFoundError: [Errno 2] No such file or directory: '.\\'\n```\n\n## Duplicated Client Mappers in Authority Service\n\nThis issue can affect customers who used Report Engine with Saga 4.1.x and then upgraded to version 4.2.x or later. To fix this, manually delete duplicated mappers in Authority Service Admin Console for *ayfie-service-account-client* client by following the steps below:\n- Go to Clients menu option in Authority Service Admin Console.\n- Click *ayfie-service-account-client* client.\n- Go to the Mappers tab.\n- Delete any duplicated mapper.\n- Restart Saga\n\n## Firewall Blocks Communication between Containers\n\nThe firewall can be set up to block some or all incoming and outgoing network traffic. Docker containers behave like virtual machines and have their own IP addresses on a virtual network named *vEthernet (nat)* as the *InterfaceAlias* (the PowerShell command *Get-NetConnectionProfile* can be used to list all networks). The containers running on an internal virtual network are normally not affected by firewall blocking. However, if one were to discover that the containers are unable to communicating with each other, then that could be explained by the firewall blocking. In that case one should investigate the firewall settings related to the virtual network.\n\nAn indication that one is experiencing this issue could for instance be that the *ayfie-locator* container is unable to connect to an otherwise healthy Postgres database during startup. To look into this one could use the PowerShell command below from inside the *ayfie-locator* container to see if one is able to reach the *ayfie-saga-db* container on its operational port 5432:\n ```\n Test-NetConnection -port 5432 ayfie-saga-db\n ```\n\n## gMSA Must Have Access to the TGGAU Attribute on User Account Objects\nIf users upon logging in to the Search UI are met by error messages and no search results, check the log file *Ayfie.Locator.RestService.log* for the presence of the following error message:\n ```\n [Via.Platform.Data.Authentication.SearchUser] System.Security.SecurityException: The user name or password is incorrect.\n at System.Security.Principal.WindowsIdentity.KerbS4ULogon(String upn, SafeAccessTokenHandle& safeTokenHandle)\n ```\n\nIf this error message is present, this could be an indication that the gMSA user doesn't have access to the *token-groups-global-and-universal* (TGGAU) attribute on user account objects, see [Some applications and APIs require access to authorization information on account objects](https://learn.microsoft.com/en-us/troubleshoot/windows-server/active-directory/apps-apis-require-access) for more information.\n"}},"macroMetadata":{"macroId":{"value":"46a8a775-d8d6-4884-b4aa-a41e7d2acfd8"},"schemaVersion":{"value":"1"},"placeholder":[{"type":"icon","data":{"url":"https://d27i9fmzbobp10.cloudfront.net/markdown-mark.png"}}],"title":"Markdown"}}}}],"version":1}

Ayfie Locator Installation Guide