Installation Guide Version 8.16 (LTS)

Owned by Black Team
Last updated: Dec 12, 2022 by Technische Redaktion
11 min read

This guide describes how to install and configure a complete yuuvis® RAD 8.x system.

Where to Find the Installers

The official installers for the yuuvis® RAD 8.x release can be found in the OS cloud URL listed in the release e-mail.

Installation Process

Requirements

Also see the System Requirements (German version here).

  • Microsoft SQL or PostgreSQL database server in one of the versions specified in the System Requirements (German version here).
  • An exclusive database instance for yuuvis® RAD. 
    • The default language of the yuuvis® RAD DB user must be set to English. 
    • The user must be a local database server user. yuuvis® RAD does not currently support logging in the db with a domain user.
    • The user must have "db_owner" (or equivalent) rights on the yuuvis® RAD database instance.
    • The installation on a Microsoft SQL Server High Availability cluster is only possible by removing the yuuvis® RAD database from the cluster for the duration of the installation, then integrating it back into the cluster afterwards. This can be done while the cluster is online. Later updates of yuuvis® RAD do not require this process.
    • The starting size and "extend by" size of the data and log files should suit your needs. 
    • If the log file size is limited, the recovery model must be set to "simple".
  • The server host names must conform with RFC 952. Specifically, they must not contain underscores ( _ ).
  • The IP- and MAC-addresses must be static and cannot be changed.
  • Firewall exceptions and/or proxy configurations/exceptions for all ports named in the System Requirements or configured differently to the setup's standard.
  • Anti-virus exceptions for all folders used by yuuvis® RAD components.
  • Microsoft .NET Framework version 4.6.2 for yuuvis® RAD designer.
  • An evergreen browser (Chrome, Firefox, Edge) in the current version for the webclient.
  • Microsoft Office in one of the versions specified in the System Requirements to run Office Add-In, Outlook Add-in (archiving) and yuuvis® RAD template-editor.
  • We also recommend installing Notepad++, Baretail, and 7-Zip.

yuuvis® RAD core-service

  • Start the setup by double-clicking, or, if you need to modify preset parameters, open an administrative command line and enter the setup command with the desired parameters.
  • Follow the dialogs in the setup.
  • Under the heading "Create database structure and base configuration":
    • Choose "yes" if you are doing a fresh install and the database is created but empty. This is the default.
    • Choose "no" if you already have an existing yuuvis® RAD database. This is the case if you are upgrading from a yuuvis® RAD 5.x installation or for example in disaster recovery situations.
  • If you chose "yes":
    • Under the heading “Enter E-Mail Parameters" you may leave the parameters empty and enter them at a later time in yuuvis® RAD management-studio. 
    • The data directory will contain the WORK/CACHE/ARCHIVE area. You can configure the archive area separately after the setup (media management in yuuvis® RAD management studio).
    • Under the sidecar service URL, instead of localhost, you must enter the IP of the server hosting the service-manager. It doesn't matter whether or not the address or the dms-sidecar microservice can already be accessed. 
    • Note the systemuser API key. You will need to enter it during the service-manager setup.
  • Start the installation.
  • Immediately initialize the database. (This is only shown if you chose "yes" in the "Create database structure and base configuration" step)
  • Do not start the service yet.
  • If the database is an Oracle database:
    By default, the oracle schema name is equal to the upper case user name and this is used automatically.
    If you have the case / the requirement, that the schema name is different from the upper case user name, please configure it as follows:
    • Open the file <core-service>\standalone\configuration\standalone-full-ha.yml
    • Naviagte to the line "<subsystem xmlns="urn:jboss:domain:datasources:5.0">" and there to "<datasource jndi-name="java:/JASDB"..."
    • Within this section, add the following new line under the line beginning with "<connection-property": <new-connection-sql>ALTER SESSION SET current_schema=schemaname</new-connection-sql>
      Replace 'schemaname' with the name of the schema. (Do not use any quotation marks.)
  • Modify the data directories (optional) :
    • For optimal configuration of the media sets please see: Configuring Media settings for Optimal Harddisk and Inode Usage
    • The JBoss data and temp directories can be configured using the JVM-options jboss.server.data.dir and jboss.server.temp.dir.
    • WORK / CACHE / ARCHIVE can be configured in the management-studio (menu entry Media) after the core-service and the service-manager have successfully started. 
  • Modify the log directory (optional) :
    • In the directory <core-service>\bin, run the yuuvis_rad_core-servicew.exe file:
      • In the Logging tab, change the log path and if desired, change the routing for stdout and stderr.
      • In the Java tab, in Java Options, modify the values for -Djboss.server.log.dir and -Dorg.jboss.boot.log.file
  • Change the service-user (optional):
    • Run the "yuuvis_rad_core-servicew.exe" file in the <server>\bin  directory.
    • Enter the technical (Windows) user in the "Log On" tab.
  • Change the heap-space settings (optional):
    • Run the "yuuvis_rad_core-servicew.exe" file in the <server>\bin  directory.
    • In the "Java" tab, modify the "Maximum memory pool" value to the desired maximum amount of working memory for the core-service (see the System Requirements for recommendations).
  • Start the service.
  • Check the log file <core-service>\logs\core-service.log with a logging program such as Baretail for the successful start of the service. The service has been successfully started when a large "yuuvis" logo is displayed as ASCII art.

The setup can be run using the command line. Use the --help option to see a list of all available parameters and options.

yuuvis® RAD designer

  • Start the setup by double-clicking.
  • Follow the dialog boxes in the setup.
  • Complete the setup.
  • You can configure and manage connections to the core-services in the designer under Settings > Connections.
  • Modify the log directory:
    • In the root directory of designer, open the logging.nlog.config file in a text editor and modify the value in the following line:
      "<variable name="logDirectory" value="${specialfolder:folder=LocalApplicationData}\OPTIMAL_SYSTEMS_GmbH\Logs\enaio designer" />"

The setup MSI supports the following parameters:

INSTALLLOCATION(optional) Target directory for yuuvis® RAD designer in the file system. Default: "C:\Program Files (x86)\OPTIMAL SYSTEMS\yuuvis RAD\designer\v6\"


Elasticsearch

  • Start the setup by double-clicking.
  • Follow the setup dialogs.
  • Under HTTP-Port, you can configure the port that Elasticsearch will listen on. This port should only be changed if the default port (9200) is already being used. For more details see below.
  • The index directory is the directory where Elasticsearch will put its index (database) files. This directory can become very large. We recommend to use SSD storage for this directory.
  • When asked for the maximum memory, configure the amount of heap space that Elasticsearch can use. This should be between 4 and 31.5 GB.
  • Start the installation.
  • Do not start the service yet.
  • Change the http and transport ports (optional unless running 2+ instances on the same machine):
    • Edit the <elasticsearch>\config\elasticsearch.yml file
    • Change the "http.port:" property to your desired port. Make sure to reflect this change in the <service-manager>\config\application-es.yml configuration file of the service-manager.
    • Change the "transport.port" property to your desired port
  • Set the repository path (optional, if no cluster is set up):
    • Edit the <elasticsearch>\config\elasticsearch.yml file
    • Edit the "path.repo:" property and set your desired repository path. Use "/" instead of "\" in the path.
      If you want to run Elasticsearch in a cluster, this path needs to be used by all cluster nodes and therefore it needs to be accessible by all cluster nodes.
  • Modify the service user (optional):
    • Run the "elasticsearch-793-service-x64w.exe" file in the <elasticsearch>\bin directory.
    • Enter the technical (Windows) user in the "Log On" tab.
  • Change heap space settings (optional):
    • Run the "elasticsearch-793-service-x64w.exe" file in the <elasticsearch>\bin directory.
    • In the "Java" tab, modify the "Maximum memory pool" value to the desired amount of heap space for the service. Make sure "Initial memory pool" is set to the same value.
    • In the "Java options" section adapt the "-Xmx" and "-Xms" settings to the desired amount of heap space.
  • Modify the data directory (optional):
    • Edit the <elasticsearch>\config\elasticsearch.yml file
    • Edit the "path.data:" property and set your desired data path. Use "/" instead of "\" in the path.
  • Modify the log directory (optional):
    • Run the "elasticsearch-793-service-x64w.exe" file in the <elasticsearch>\bin directory.
    • Modify the log directory in the "Logging" tab.
    • Edit the file <elasticsearch>\config\elasticsearch.yml
    • Add a line with "path.logs: " and the path to your desired logs folder. Use "/" instead of "\" in the path.
  • Start the service. (check es-red.log file in the logs folder for correct startup)
  • Execute the <elasticsearch>\bin\elasticsearch-set-initial-passwords.bat file
  • Copy the password of the 'elastic' user. (Alternatively, you can open the <elasticsearch>\config\built-in.usr file and look it up there.)


yuuvis® RAD service-manager

  • Double-click to start the setup.
  • Follow the setup dialogs.
  • Under HTTP-Port, you can configure the service-manager services port. This port has no special significance but should only be changed if the default port (7281) is already being used.
  • Under "Enter yuuvis® RAD core-service parameter", enter the IP address of the server that hosts the core-service.  
    Also enter the systemuser API key that you noted during the core-service setup.
  • Under "Enter database parameter" at "database server" enter the IP address under which the database used for yuuvis® RAD (core-service) can be reached. You may need to modify the port (1433 is generally correct for MSSQL databases).
    Also enter the database name of the database used for the yuuvis® RAD (core-service), as well as the credentials of the database user designated for yuuvis® RAD into the corresponding fields.
  • Under "Enter enaio rendition-plus parameter", enter the IP address and the port of the server that hosts yuuvis® RAD rendition-plus. Rendition-Plus does not yet have to be installed. If a different port is selected during installation of Rendition-Plus, you must enter it instead of the default 8090.
  • Under "Configuration of Elasticsearch" enter the IP(s) and port(s) of the elasticsearch servers, the password of the 'elastic' user that was generated when executing the file <elasticsearch>\bin\elasticsearch-set-initial-passwords.bat and the language code for the language that the Intrafind linguistic plugin should support. The language code can be one of the following values: de,en,es,fr,it. Set the language code of the language that is used the most in your system. All other languages active in your system will have basic support. Attention: only one value may be set to this parameter.
  • Under "IP Filter for dms-sidecar", enter the IP addresses and/or IP address ranges that should get access to the dms-sidecar. The dms-sidecar provides access to the core-service REST-WS API and thus access to it should be limited to the necessary servers only. The value is a regex expression, refer to this page for more details.
  • Complete the setup but do not start the service yet.

  • If the structure-service and the discovery-service are on different machines and/or the discovery-service is running on a port different than the standard (7261), edit the file <service-manager>\config\servicewatcher-sw.yml and add the "env" parameter with the corresponding values (host and/or port of the discovery-service) to the section of the structure-service 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: 10.10.1.2
        EUREKA_PORT: 9261


  • The following settings are optional:

    • If you are setting up a productive system and expect to have a very high amount of documents (i.e. > 50 Mio. documents) and/or data in elasticsearch (many metadata fields and/or big fulltexts) consider increasing the number of shards from 1 (the default) to a more appropriate one. If you have more than one node in your elasticsearch cluster, use at least the number of nodes as the number of shards. We do not recommend to go higher than 3 or 4 times of the number of nodes as this would rather lower the performance again. See also https://www.elastic.co/guide/en/elasticsearch/reference/current/size-your-shards.html for more details.
      To increase the number of shards, edit the file <service-manager>\config\index-prod.yml and add the line shown below. This must be done before the first start of the service-manager (index-service) to take effekt (otherwise a reindex using the index-service's swagger-ui endpoint is necessary).

      osfts.number-of-shards: 3

    • Change the rollover settings for the logfiles:

      • Open the file "<service-manager>\config\servicewatcher-sw.yml" and complete the logging section as shown below.

        logging:
           file: ./../../logs/services.log
           config: ./config/logback.xml
           maxDays: 30
           totalSizeCap: 10GB

        The parameter maxDays determines for how many days a log file should be saved.
        The parameter totalSizeCap limits the total size of all log files to the specified value.

    • Define gateway authentication method and custom endpoints:

      • In the "<service-manager>\config\gateway-prod.yml" file, you can adjust the authentication mechanism for the services by setting the "authentication.filter.*" properties as follows:

        • Basic-authentication:\ntlm: false, form: true, basic: true
        • NTLM (SSO) authentication: ntlm: true, form: false, basic: false

      • You can also define additional (external) endpoints as follows:

        routing.endpoints

    • Modify the data directories:
      • In the <service-manager>\bin directory, run the enaio_red_service-managerw.exe file.
      • In the "Java" tab, under Java Options, set the temp directory with the JVM option Djava.io.tmpdir. You can use the options –Dcatalina.base and –Dcatalina.home to set the Tomcat work directories.
      • In the directory <service-manager>\config, open the application-prod.yml file and modify enaio.data.path. The relative path to the .jar files is <service-manager>\apps\<*service>. If you use './../..', you end up in the service-manager root directory.
    • Modify the log directory:
      • In the <service-manager>\bin directory, run the enaio_red_service-managerw.exe file.
      • In the "Logging" tab, modify the log path and, if desired, set up or change the redirects for stdout and stderr.
      • In the "Startup" tab, modify the "--logging.file" argument. The relative path to the .jar files is under <service-manager>\apps\<*service>. Use './../..' to point to the service-manager root directory.
      • In the <service-manager>\config, open the servicewatcher-sw.yml file and in the "logging" section, modify "file". The relative path to the .jar files is under <service-manager>\apps\<*service>. Use './../..' to point to the service-manager root directory.
    • Modify the service user:
      • In the <service-manager>\bin directory, run "enaio_red_service-managerw.exe".
      • (Optional) In the "Log On" tab, enter the technical (Windows) user.
  • Start the service.
  • You can see an overview of the running services at http://<ip>:7273. This is the Spring Boot Admin service. It can be used to permanently monitor the services.
  • It can take several minutes for all the services to start successfully.
  • "Connection refused" exceptions appearing in the service-manager log file in the first few minutes are nothing to worry about.

The setup can be run using the command line. Use the --help option to see a list of all available parameters and options.

 
yuuvis® RAD rendition-plus

  • Start the setup by double-clicking.

  • Follow the dialogs in the installer.
  • The HTTP port determines through which port the rendition-plus service can be contacted. If you deviate from the default 8090, you must modify the service-manager configuration file application-red.yml accordingly.
  • In "enaio Rendition sidecar" enter the IP address of the server hosting the service-manager. Important: 127.0.0.1 is only valid if both services are installed on the same machine. If not, you must use the externally visible IP address.
  • Complete the setup but do not start the service yet.

  • In the file <rendition-plus>\webapps\osrenditioncache\WEB-INF\classes\config\config.properties, modify the maximum size of the rendition cache with the cache.maxsize parameter if the preset of 500 GB does not fit your needs. The smaller you make the cache size, the more often existing rendition files are displaced and have to be created again when requested by a call.

  • Modify the data directories (optional):
    • In the <rendition-plus>\bin directory, run "enaio red rendition-plusw.exe".
    • In the "Java" tab, under Java Options, set the temp directory with the JVM option -Djava.io.tmpdir. You can use the options –Dcatalina.base and –Dcatalina.home to set the Tomcat work directories.
    • In the file <rendition-plus>\webapps\osrenditioncache\WEB-INF\classes\config\config.properties, you can modify rendition-cache specific data directories.
      • To modify the Cache directory, use the sor.root key.
      • To modify the Jobs directory, use the job.root key.
      • To modify the Temp directory, use the temp-base key.
      • To modify the Database-Root directory, use the db.root key.
    • In the file <rendition-plus>\webapps\renditionplus\WEB-INF\classes\config\config.properties, you can modify rendition-plus specific data directories.
      • The temp directory can be adjusted by the temp-base key.
  • Modify the log directory (optional):
    • In the <rendition-plus>\bin directory, run "enaio red rendition-plusw.exe".
    • In the "Logging" tab, modify the log path and, if desired, set up or change the redirects for stdout and stderr.
    • In the <rendition-plus>\conf directory, open the logging.properties file and modify all lines that correspond to a *.directory key. (As a rule, $(catalina.base) corresponds to the rendition-plus root directory.)
    • Open the <rendition-plus>\webapps\osrenditioncache\WEB-INF\classes\log4j.properties file in a text editor.
      • Modify the log4j.appender.OsRenditionCacheLogFile.File key to change the path of OsRenditionCacheLogFiles.
      • Modify the log4j.appender.JobMonitoringLogFile.File key to change the path of JobMonitoringLogFiles.
    • Open the <rendition-plus>\webapps\renditionplus\WEB-INF\classes\log4j.properties file and modify the log4j.appender.RenditionPlusLogFile.File key to change the path of RenditionPlusLogFiles.
  • Modify the service user (optional):
    • In the directory <rendition-plus>\bin, run the "enaio red rendition-plusw.exe" file.
    • (Optional) In the "Log On" tab, enter the technical (Windows) user.
  • Start the service
  • Check the log files for correct startup and/or check the service-manager admin (http://<service-manager-ip>:7273) if the renditionsidecar is available.

The setup can be run using the command line. Use the --help option to see a list of all available parameters and options.

yuuvis® RAD agent, yuuvis® RAD Office  Add-in,  yuuvis® RAD Outlook Add-in and yuuvis® RAD template-editor

  • Start the MSI Setup by double-clicking it.
  • Other than an installation path, the setups need no additional input and complete on their own.
    If you are installing the MSIs using the console (e.g. Microsofts software distribution) you can specify the parameter "installdir" to change the default installation path.
  • Modify the Log Directories:
    • The log directories cannot be modified at this time.
    • Log files for the add-ins can be found in %LOCALAPPDATA%\OPTIMAL_SYSTEMS_GmbH\Logs, in the corresponding subfolders.
    • Log files for the agent can be found in %APPDATA%\enaio red agent\logs.

yuuvis® RAD metrics-manager



For security reasons, the passwords for the system accounts should be changed after the installation is complete.