Installing yuuvis® RAD service-manager

To install yuuvis® RAD service-manager, follow these steps:

1. Copy the yuuvis_rad_service-manager installation directory to the file system of the computer on which you want to install yuuvis® RAD service-manager with the microservices.

2. Launch yuuvis_rad_service-manager_setup-<Version>.exe from the installation directory.

The installation wizard will start. Follow the steps described by the installation wizard.

3. Enter the following microservice parameters.

   The central microservice parameters will be entered in the configuration files of the microservices. Subsequent changes can be made via the Service Application Manager SAM.

Technical service name/ Service display name	Technical service name and service display name for service control.
HTTP port	Port of yuuvis® RAD service-manager. Default: 7281
Data directory	Data directory for yuuvis® RAD service-manager.
Server	IP address of the computer on which yuuvis® RAD core-service is installed.
API key	Enter the API key of the system user. The API key required here is shown when yuuvis® RAD core-service is installed. Access from yuuvis® RAD service-manager to yuuvis® RAD core-service is made in the context of the system user with full access rights for this.
Database type	MSSQL PostgreSQL Continued support for Oracle databases will only be available for existing installations.
Database server	IP address of the computer on which the database is installed.
Database server port	Port of the database computer.
Database instance	Database instance name
Database name	Database name
Schema name	Schema name of the database.
Database user	Name of the technical user for database access.
Database password	Password of the technical user for database access.
JDBC string	The JDBC string for the database connection is created automatically from the database information. Only edit the entry if changes need to be made for specific environments.
Rendition server	IP address of the rendition service. The rendition service can be installed after yuuvis® RAD service-manager.
Rendition server port	Rendition service port. Default: 8090
Tesseract OCR	Tesseract is installed with yuuvis® RAD service-manager and, if this option is activated, preconfigured as an OCR component. Enter the required languages for Tesseract. The language configuration is entered in the <service-manager>\config\ocr-prod.yml configuration file and can be edited at a later time. tesseract:   languages: deu,eng
Elasticsearch: Server and port	IP address of Elasticsearch and port. Default: 9200
Elasticsearch: Password	Password of the Elasticsearch installation. The password is stored in the application-es.yml file.
Language codes	Language for the Linguistic plugin. One language can be activated: English (en), French (fr), German (de), Italian (it), or Spanish (es). Licenses can be acquired from OPTIMAL SYSTEMS and integrated to unlock multiple and additional languages.
IP filter for dms-sidecar	IP addresses from which it is possible to access yuuvis® RAD core-service via the 'dms-sidecar' service. 127.0.0.1 and the address of yuuvis® RAD service-manager are prepopulated. These addresses are required for this IP filter and are generally all that is needed. The addresses are entered in the application-prod.yml configuration file located in the \config directory.

4. Adjust the service parameters before you start the service:

   • Launch yuuvis_rad_service_managerw.exe from the \service-manager\bin\ directory.

   Service parameters:

   Log On > Account	Account for login to the service yuuvis® RAD service-manager requires an administrative account.
   Logging > Level	Optional: Logging level for service logging
   Logging > Path	Optional: Path for service logs
   Logging > Stdout	Optional: Redirect the standard output to a file
   Logging > Stderror	Optional: Redirect the standard error output to a file
   Startup > Arguments	The port of yuuvis® RAD service-manager can be modified. Default: 7281
   Java > Java options	Optional: Modify Tomcat data directories.

5. If the 'structureservice' and 'discoveryservice' microservices are running on different computers and/or the Discoveryservice is running on a port other than the default port (7261), then add the appropriate values, host/port of the Discoveryservice, to the configuration file <service-manager>\config\servicewatcher-sw.yml in the Structureservice section as follows:

   - name: structureservice
     type: executable
     profiles: prod,red,es,mq
     instances: 1
     port: 7461-7469
     path: ${appBase}/structureservice/structure-service.exe
     env:
       EUREKA_HOST: discovery-host
       EUREKA_PORT: discovery-port

6. Setting for authentication via the 'GATEWAY' microservice

   The authentication can be configured via the gateway-prod.yml configuration file in the \service-manager\config\ directory.

   • Settings for login form (default setting)

     The yuuvis® RAD user name and the yuuvis® RAD password are used for logging in:

     authentication.filter.ntlm: false
     authentication.filter.form: true
     authentication.filter.basic: true
     authentication.filter.ldap: false
     authentication.filter.oauth2: false

   • Settings for single sign-on via NTLM

     Login is performed automatically via the Windows domain session used by the user:

     authentication.filter.ntlm: true
     authentication.filter.form: false
     authentication.filter.basic: false
     authentication.filter.ldap: false
     authentication.filter.oauth2: false

     If the user’s domain should be taken into account during login because it is specified in the user management, then an additional parameter can be specified:

     authentication.ntlm.usersubstitutionpattern:

     Default: '#USER#'

     Specify the format in which the user name and domain are specified in the user management. Examples: '#USER#@#DOMAIN#.com' '#USER#@#FQDOMAIN#' Values: '#USER#', '#DOMAIN#', '#FQDOMAIN#' #FQDOMAIN# is the 'Fully Qualified Domain Name'.

     By default, the domain is not used so it does not need to be configured.

     The log for the single sign-on can also be specified as: NTLM (default) or Negotiate. You can specify Negotiate for logins via Kerberos:

     authentication.ntlm.protocol:

     Default: 'NTLM'

     Specify 'Negotiate' for login via Kerberos.

     Authentication is done via the session token for the domain. The users also need to be created as yuuvis® RAD users, for example via the Import organization operation. The password is not stored in yuuvis® RAD.

     A prerequisite for successful single sign-on authentication is the correct configuration of the security zone of the yuuvis® RAD web client URL and permission for the transfer of the session token in the domain group policies or in the settings of the desired server or client workstations. Further information on this can be found here, for example.

   • Settings for integrating an identity provider using a reverse proxy

   yuuvis® RAD gateway uses header authentication. The reverse proxy needs to set this header so that a valid session can be established.

   This login procedure allows you to log in without a password. yuuvis® RAD gateway should be secured via IP filters or via a firewall to only allow access via the reverse proxy.

   To do this, you will need to add the following lines to the gateway-prod.yml configuration file:

   authentication.filter.external: true
   authentication.filter.header.name: 'X-User'
   
   routing.logoutSuccessRedirect: '/app/logout'
   authentication.exposed.endpoints: '/app/logout'
   
   server.forward-headers-strategy: NATIVE

   Parameters:

   authentication.filter.external	true Label for using an external identity provider.
   authentication.filter.header.name	Header that is configured for the reverse proxy. The next login filter is called up if the configured header is not found or contains an invalid user name. By default the next filter is the filter that has the value true in the gateway-prod.yml in the order listed. 'NTML' always has priority over 'FORM' or 'Basic'.
   routing.logoutSuccessRedirect	Page to which you are redirected after logging out. A directory with an index.html file must be specified. The directory must be located in the installation directory of yuuvis® RAD service-manager below the \webresource\public\ directory. The \webresource\public\ directory is specified using /app.
   routing.logoutSuccessRedirect	Page to which you are redirected after errors. The page must be created according to the page to which you are redirected after logging out.
   server.forward-headers-strategy	NATIVE Required Spring Boot parameter.

   The following setting in the application-prod.yml configuration file from the \config directory of yuuvis® RAD service-manager is also required:

   server.max-http-header-size: 10MB
   server.max-http-request-header-size: 10MB

   The Change password function is not available when integrating an identity provider in yuuvis® RAD client.

   Keycloak and Azure AD/Entra ID can be connected directly.

   • LDAP authentication settings

     The login is done via the Windows Active Directory (domain) or LDAP server user name and password:

     authentication.filter.ntlm: false
     authentication.filter.form: true
     authentication.filter.basic: true
     authentication.filter.ldap: true
     authentication.filter.oauth2: false

     If 'LDAP' is activated, 'FORM' or 'BASIC' must always be activated as well.

     Authentication is then performed against the (domain) directory service, and the users must have also been set up as yuuvis® RAD users, such as via the Import organization operation.

     The passwords are not stored in yuuvis® RAD, as is the case with 'NTLM'. However, users must enter their password when logging in.

     In addition, the data for the connection to the directory service must be specified:

     authentication.filter.ldap: true
     
       ldap:
         defaultpostfix: '@DOMAIN1.local'
         usedefaultforlogin: false
         provider:
           - domain: 'DOMAIN1.local'
             providerurl: 'ldap://10.6.0.119:389'
           - domain: 'DOMAIN2.local'
             providerurl: 'ldap://10.6.0.120:389'
           - domain: 'DOMAIN3\'
             providerurl: 'ldap://10.6.0.121:389'
         excludeuser:
           - root2
           - root

     Parameters:

     provider	Providers are specified with the domain and a valid fully qualified LDAP server URL. You can define multiple providers.
     defaultpostfix	User names can be forwarded with a domain postfix extended to the appropriate provider from the list for login. This means that users only have to enter the user name without the domain, i.e., instead of 'Name@Domain', they only need to enter their name. If users enter the user name with '@', the entry will not be expanded.
     usedefaultforlogin	If yuuvis® RAD user names are created with a domain prefix or postfix, specify 'true' here; otherwise, set it to 'false'. Users from directory services can be transferred to the yuuvis® RAD user administration via a synchronization operation. Data can be structured and created with a postfix.
     excludeuser	List of users who are not logged in via the directory service, but as yuuvis® RAD users.

7. Other optional changes:

   • HTTPS

   HTTPS can be activated.

   • SameSite attribute

   It is possible to set the SameSite attribute for yuuvis® RAD cookies: strict, lax, none.

   The SameSite attribute is entered in a new line in the gateway-prod.yml configuration file in the \service-manager\config\ directory: cookie.samesite: 'strict'

   • Context path

   A context path is used as the prefix for all URLs. yuuvis® RAD gateway can be accessed via a context path if it is running at an address as one of several services. Integration into portals is therefore possible, for example.

   • A context path is integrated via the gateway-prod.yml configuration file in the \<service-manager>\config\ directory:

     server.servlet.context-path: '/yuuvis/contextpath'
     management.server.port: 7396

     • server.servlet.context-path: Any number of path segments with a / at the start (leading) but not the end (closing) are entered.

     • management.server.port: Free port that is accessible for other yuuvis® services; default: 7396. Management URLs are called under the defined port not the context path.

     A context path can be specified for each instance if several instances of the 'Gateway' microservice are running. A separate management port is also required in each case.

     For the other instances of the 'Gateway' microservice, create a gateway-<profilename>.yml file as a profile and enter the context path and management port there.

     Example of a gateway-context.yml profile file:

     server.servlet.context-path: '/yuuvis/contextpath_2'
     management.server.port: 7397

     The management port needs to be specified using consecutive numbering.

     The profile is assigned to the corresponding 'Gateway' microservice via the servicewatcher-sw.yml configuration file.

     Example of a profile assignment via the servicewatcher-sw.yml configuration file:

     - name: gateway
       type: microservice
       profiles: prod,cloud,red
       instances: 1
       memory: 256M
       port: 80
       path: ${appBase}/gateway/gateway-app.jar
       args:
       - --management.server.port=7396
       
     - name: gateway_2
       type: microservice
       profiles: prod,cloud,red,context
       instances: 1
       memory: 256M
       port: 81
       path: ${appBase}/gateway/gateway-app.jar
       args:
       - --management.server.port=7397

     The management port can be specified in servicewatcher-sw.yml as in the example instead of in profile files.

     If a context path is configured, caching should be activated for the 'clientservice' service via the following entry in the client-prod.yml file: spring.web.resources.chain.cache: true.

   • Instances and memory assignments

   Microservice instances can be added and microservices can be deactivated (instances: 0) via the servicewatcher-sw.yml configuration file in the \service-manager\config\ directory.

   The memory assignment for the individual microservices can be modified.

   • 'messagingservice' service

   The default size for the KAHADB database of the 'messagingservice' service is 50 GB. This size is sufficient for up to 100 million messages. The size can be increased if more messages are expected.

   Use the application-mq.yml configuration file located in the \service-manager\config\ directory to specify the value in bytes using the following parameter:

   spring.activemq.storeLimitInBytes

8. Start the yuuvis® RAD service-manager service.

   It may take several minutes to start yuuvis® RAD service-manager and the microservices.

If yuuvis® RAD service-manager does not start the microservices, then check the following settings in the registry editor: key: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\PerfProc\Performance\Disable Performance Counters (REG_DWORD). The value must be specified as 0.
If the operating system's language setting was changed and the microservices do not start, then check the following settings in the registry editor: key: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Perflib\009. The values need to be entered in English. Resetting the language change usually solves the problem. Information can also be found at Microsoft.