How to Install 10.x

Owned by Technische Redaktion
Last updated: Apr 26, 2024
11 min read

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

Where to Find the Installers

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

Installation Process

Requirements

Also see the https://help.optimal-systems.com/yuuvisRAD/v100/admin/en/index.html in our help portal (German version here).

  • Microsoft SQL or PostgreSQL database server in one of the versions specified in the System Requirements (see above).

  • An exclusive database instance for yuuvis® RAD. 

    • The default language of the yuuvis® RAD DB user must be set to English (us_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.

    • 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 ( _ ).

  • 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.8 and Microsoft Edge WebView2 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

  1. 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.

  2. Follow the dialog in the setup.

  3. Under the heading Create database structure and base configuration:

    1. Choose yes if you are doing a fresh install and the database is created but empty. This is the default.

    2. 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.

  4. If you chose yes:

    1. 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. 

    2. 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).

    3. 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. 

    4. Make a note of the systemuser API key. You will need to enter it during the service-manager setup.

  5. Start the installation.

  6. Immediately initialize the database. 
    (This is only shown if you chose yes in the Create database structure and base configuration step)

  7. Do not start the service yet.

  8. 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, execute the following sql-statement to set a logon-trigger setting the correct schema name:

    1. CREATE OR REPLACE TRIGGER logon_session_schema AFTER LOGON ON DATABASE BEGIN execute immediate 'ALTER SESSION SET current_schema="<schemaname>"'; END;

      Replace <schemaname> with the name of the schema.

  9. Modify the data directories (optional) :

    1. For optimal configuration of the media sets, see: Configuring Media settings for Optimal Harddisk and Inode Usage

    2. The JBoss data and temp directories can be configured using the JVM-options jboss.server.data.dir and jboss.server.temp.dir.

    3. WORK / CACHE / ARCHIVE can be configured in the management-studio (menu entry Media) after the core-service and the service-manager successfully started. 

  10. Modify the log directory (optional) :

    1. In the directory <core-service>\bin, run the yuuvis_rad_core-servicew.exe file:

      1. In the Logging tab, change the log path and if desired, change the routing for stdout and stderr.

      2. In the Java tab, in Java Options, modify the values for -Djboss.server.log.dir and
        -Dorg.jboss.boot.log.file

  11. Change the service-user (optional):

    1. Run the yuuvis_rad_core-servicew.exe file in the <server>\bin directory.

    2. Enter the technical (Windows) user in the Log On tab.

  12. Change the heap-space settings (optional):

    1. Run the yuuvis_rad_core-servicew.exe file in the <server>\bin directory.

    2. In the Java tab, change the Maximum memory pool value to the desired maximum amount of working memory for the core-service (for recommendations, see: System Requirements in the help portal).

  13. Start the service.

  14. 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

  1. Start the setup by double-clicking.

  2. Follow the dialog boxes in the setup.

  3. Complete the setup.

  4. You can configure and manage connections to the core-services in the designer under Settings > Connections.

  5. 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\v9\

INSTALLLOCATION

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

Elasticsearch

  1. Start the setup by double-clicking.

  2. Follow the setup dialog.

  3. 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.

  4. 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.

  5. When asked for the maximum memory, configure the amount of heap space that Elasticsearch can use. This should be between 6 and 31.5 GB.

  6. When asked for the language pack, choose if you want Elasticsearch to optimize for european or asian languages

  7. Start the installation.

  8. Do not start the service yet.

  9. Change the http and transport ports (optional unless running 2+ instances on the same machine):

    1. Edit the <elasticsearch>\config\elasticsearch.yml file

    2. 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.

    3. Change the transport.tcp.port property to your desired port

  10. Set the repository path (optional, if no cluster is set up):

    1. Edit the <elasticsearch>\config\elasticsearch.yml file

    2. 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.

  11. Modify the service user (optional):

    1. Run the yuuvis_rad_elasticsearchw.exe file in the <elasticsearch>\bin directory.

    2. Enter the technical (Windows) user in the Log On tab.

  12. Change heap space settings (optional):

    1. Run the yuuvis_rad_elasticsearchw.exe file in the <elasticsearch>\bin directory.

    1. 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.

  13. Modify the data directory (optional):

    1. Edit the <elasticsearch>\config\elasticsearch.yml file

    2. Edit the path.data: property and set your desired data path. Use "/" instead of "\" in the path.

  14. Modify the log directory (optional):

    1. Run the yuuvis_rad_elasticsearchw.exe file in the <elasticsearch>\bin directory.

    2. Modify the log directory in the Logging tab.

    3. Edit the file <elasticsearch>\config\elasticsearch.yml

    4. Add a line with path.logs: and the path to your desired logs folder. Use "/" instead of "\" in the path.

  15. Modify the temp directory (optional):

    1. Run the yuuvis_rad_elasticsearchw.exe file in the <elasticsearch>\bin directory.

    2. Switch to the Java tab and to the Java options section.

    3. Change the property -Djava.io.tmpdir to your desired temp directory
      (e.g. -Djava.io.tmpdir=D:\yuuvis-data\elasticsearch\temp).

    4. If this directory does not exist yet, create it manually (otherwise elasticsearch won't start).

  16. Start the service. (check es-red.log file in the logs folder for correct startup)

  17. Execute the <elasticsearch>\bin\elasticsearch-set-initial-passwords.bat file

  18. 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

  1. Double-click to start the setup.

  2. Follow the setup dialog.

  3. 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.

  4. 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.

  5. 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.

  6. 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.

  7. Under Configuration for Tesseract OCR, choose if you want to use Tesseract as the OCR engine or not. Also, if you want to use Tesseract, enter the language code for which language Tesseract should optimize. See https://help.optimal-systems.com/yuuvisRAD/v100/admin/en/administration/installation/inst_tsk_finereader-install.htm for further information. If you don’t want to use OCR at all or another OCR engine (e.g. ABBYY FineRader) then choose “not activated”.

  8. Under Configuration of Elasticsearch, if the Elasticsearch installation is on a different machine than the service-manager installation, replace the value 127.0.0.1:9200 of the “server and port” field with the IP and port of the Elasticsearch machine. Also enter the password for the elastic user that was created when installing Elasticsearch and the language code for which you want elasticsearch to optimize. The possible values are: de, en, es, fr, it.
    Set the language code of the language that is used the most in your system. This language will be supported by the intrafind lingustic plugin. All other languages active in your system will have basic support.
    Attention: Only one value may be set to this parameter.

  9. 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.

  10. Complete the setup but do not start the service yet.

  11. 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

  12. Optional settings:

    1. 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 effect (otherwise a reindex using the index-service's swagger-ui endpoint is necessary).

      osfts.number-of-shards: 3

    2. 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.

    3. Define gateway authentication method and custom endpoints:

      1. 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

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

        routing.endpoints

    4. Modify the data directories:

      1. In the <service-manager>\bin directory, run the enaio_red_service-managerw.exe file.

      2. 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.

      3. 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.

    5. Modify the log directory:

      1. In the <service-manager>\bin directory, run the enaio_red_service-managerw.exe file.

      2. In the Logging tab, modify the log path and, if desired, set up or change the redirects for stdout and stderr.

      3. 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.

      4. 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.

    6. Modify the service user:

      1. In the <service-manager>\bin directory, run enaio_red_service-managerw.exe.

      2. (Optional) In the Log On tab, enter the technical (Windows) user.

  13. Start the service.

  14. 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.

  15. It can take several minutes for all the services to start successfully.

  16. "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

  1. Start the setup by double-clicking.

  2. Follow the dialogs in the installer.

  3. 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.

  4. 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.

  5. Complete the setup but do not start the service yet.

  6. 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.

  7. Modify the data directories (optional):

    1. In the <rendition-plus>\bin directory, run enaio red rendition-plusw.exe.

    2. 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.

    3. 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.

    4. 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.

  8. Modify the log directory (optional):

    1. In the <rendition-plus>\bin directory, run enaio red rendition-plusw.exe.

    2. In the Logging tab, modify the log path and, if desired, set up or change the redirects for stdout and stderr.

    3. 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.)

    4. Open the <rendition-plus>\webapps\osrenditioncache\WEB-INF\classes\log4j.properties file in a text editor.

      1. Modify the log4j.appender.OsRenditionCacheLogFile.File key to change the path of OsRenditionCacheLogFiles.

      2. Modify the log4j.appender.JobMonitoringLogFile.File key to change the path of JobMonitoringLogFiles.

    5. 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.

  9. Modify the service user (optional):

    1. In the directory <rendition-plus>\bin, run the enaio red rendition-plusw.exe file.

    2. (Optional) In the Log On tab, enter the technical (Windows) user.

  10. Start the service

  11. 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

  1. Start the MSI Setup by double-clicking it.

  2. 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.

  3. Modify the Log Directories:

    1. The log directories cannot be modified at this time.

    2. Log files for the add-ins can be found in %LOCALAPPDATA%\OPTIMAL_SYSTEMS_GmbH\Logs, in the corresponding subfolders.

    3. Log files for the agent can be found in %APPDATA%\enaio red agent\logs.

yuuvis® RAD metrics-manager

Please refer to the metrics-manager Installation Guide.

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