Installation

This page describes the new installation of smart.finder. Make sure that the specified system requirements are met, see System Requirements.

If you want to update an existing installation, continue with Update an existing installation.

Installation of smart.finder

smart.finder consists of two WAR archives, one for the server and one for the standalone client. These files can be found here:

  • [RELEASE-FOLDER]/smartfinder.war

  • [RELEASE-FOLDER]/smartfinder-search.war

Prior to starting the Tomcat process, the following Java options must be set, which are required by different components of the system:

  • solr.enableRemoteStreaming=true

  • solr.enableStreamBody=true

The runtime variables can be set as environment variables or as Java options in the Tomcat configuration.

Beispiel für Linux-Umgebung via Shell
export JAVA_OPTS="$JAVA_OPTS -Dsolr.enableRemoteStreaming=true -Dsolr.enableStreamBody=true

Install the server application

Start with installing the search service webapp smartfinder-search.war.

  1. Optionally, you can change the name of the WAR files. The name will appear in the URL to the application.

  2. Make sure the Tomcat server is started.

  3. Copy the WAR file into the folder %TOMCAT%\webapps. The file will then be unpacked automatically.
    Alternatively, you can use Tomcat Manager to install the WAR file. When the Tomcat service is started, you can access Tomcat Manager at http://<yourserver>:8080/manager/html.

  4. To use the integrated user authentication system in map.apps, the default passwords for the administrator and editor users must be set. Please read the section on Security aspects for further instructions.

If you rename the WAR file in the standard system, the file system path of the search index also changes and needs to be adjusted.

When the installation was successful, the web application is now available at the following URL:

  • https://<yourserver>/smartfinder-search

Install the client application

There are two ways to install the client application:

  • As standalone client
    You install a web application WAR file for the smart.finder client UI in the same way you installed the server web application. The client UI will run right away with few configuration and you don’t need to install any additional app or JavaScript bundles. Choose this option if you do not have a running map.apps installation available.

  • As apps in an existing map.apps instance
    The bundles for the client apps as well as the apps are installed in an existing map.apps instance. This is the recommended way if you have a running map.apps instance. map.apps makes it easier to manage different apps and bundles. It provides an intelligent code editor that helps in authoring and editing apps.

Installation as standalone client

To install the smart.finder client app as a standalone web application, perform the exact steps as described in Install the server application, but use instead of smartfinder-search.war the file smartfinder.war.

When installed successfully, the client web application is then accessible through the following URL:

  • https://<yourserver>/smartfinder.

The Standalone Client comes with the following apps:

  • https://<yourserver>/smartfinder/?lang=en&app=full-page: Shows a client in a typical search engine style.

  • https://<yourserver>/smartfinder/?lang=en&app=full-screen-map: Shows a full screen map in the background. Search results are displayed in a sidebar on the right.

  • https://<yourserver>/smartfinder/?lang=en&app=full-screen-map-multicore: Demonstrates a scenario with multiple search cores. A core is an index that can be accessed by the client to search for certain types of information.

If you use the security mode INTEGRATED, change the administrator password after installation using the property security.user.admin.pw, see also Web Application Security

Using an existing map.apps instance

If you have an existing map.apps installation available, you can install the required apps and JavaScript bundles for smart.finder there.

Install the bundles

  1. In map.apps Manager log in as admin user.

  2. Open the Bundles tab.

  3. Click the + button above the list of installed bundles.

  4. Upload the file [RELEASE-FOLDER]/ct-smartfinder-js-2.5.1.jar. This file contains all JavaScript bundles for smart.finder.

  5. If you want to use the map.apps Smart Search Bundles, also upload the file [RELEASE-ORDNER]/ct-smartsearch-js-2.5.1-single.jar.

As soon as the upload is complete, the smart.finder bundles are appended to the list of installed bundles. To make it easier to distinguish the smart.finder bundles from other bundles, their names always start with the abbreviation sf_.

Install the apps

  1. In map.apps Manager log in as admin user.

  2. Open the Apps tab.

  3. Click the + button above the app list. The New App wizard launches.

  4. Type a name and a title for the app and proceed to the step for uploading your app.

  5. From the folder [RELEASE-FOLDER]/resources/apps, upload the desired app.

  6. Proceed with the next steps in the wizard until the wizard is complete.

  7. Launch the app by clicking the Launch button for your new app on the right.

Install Job Manager

smart.finder Job Manager is a plugin for map.apps Manager and is used to create and manage indexing jobs. To install it, proceed as follows:

  1. Open the map.apps configuration file application.properties. This is usually located in the folder [USER_HOME]/.mapapps.

  2. Look for the entry manager.config.viewbundles. If it already exists, append the value sf_jobadmin to the end. If it does not yet exist, add the entry with the following value.

    Sample for manager.config.viewbundles
    manager.config.viewbundles=appmanagement,reportmanagement,bundlemanagement,mapapps-github-manager,bundleupdatechecker,sf_jobadmin

Restart Tomcat and reload map.apps Manager in the web browser. There should now appear a new tab Indexing jobs.

Minimal configuration

smart.finder URL configuration

After installing the client web application (or the bundles and apps) and the server web application, you need to tell the client the URL of the server application for sending search queries. Add the following entry to the application.properties file of map.apps:

finder.service.url=https://<yourserver>/ct-finder-server-webapp-[VERSION]
smart.finder and map.apps under different domains

If the smart.finder server component is accessible under a different domain name than map.apps, the client apps will have issues when making cross-domain HTTP requests to the smart.finder server component. Make sure that the map.apps proxy servlet is enabled to access the smart.finder server. In this case, you should add the client’s domain name to the CORS configuration property cors.allowed.origins in the application.properties file of the smart.finder server webapp.

If you have trouble with CORS, you can also use the map.apps proxy servlet. For more information, see CORS settings.
smart.finder map.apps app configuration

To run the supplied apps, everything is now configured. These apps provide you with an initial state for your own customizations.

If you want to integrate smart.finder into one of your own custom map.apps apps, open map.apps Manager and add the bundle sf_full-screen-map to this app. The bundle loads all necessary additional bundles to enable searching with omnisearch (the default bundle in map.apps for keyword searches) and displaying results in a popup.

For more information on configuration, see section Apps and bundles.

Install CLI

smart.finder CLI is a tool to manage indexing jobs via command line.

finderctl is distributed as an executable file for Windows and Linux operating systems (x86-64 architecture). It is located at:

  • [RELEASE-FOLDER]/cli/linux_x64/finderctl for Linux.

  • [RELEASE-FOLDER]\cli\windows_x64\finderctl.exe for Windows.

Copy finderctl directory
The directory containing the executable file can also be copied to any other location. The auxiliary files located next to the executable file may be needed at runtime by finderctl and should be copied as well.

Add the location to the search path of your system (e.g. $PATH or %PATH%). This way you can run finderctl without having to specify the full path. Depending on your operating system, it may be necessary to authorize finderctl to run.

Verify the installation by running the following command:

~$ finderctl --version

Security aspects

You manage access to safety-critical functions completely in the server component of smart.finder. This includes creating indexing jobs, filling or deleting the index, and reading specific administrative interfaces. Each of these cases requires user authentication, which is requested in the browser.

Web Application Security

smart.finder provides endpoints for query and write access to the index or other core functions. All transactional endpoints, as well as the entire index management, can be protected by the following security modes:

NONE

No protection.

INTEGRATED

This is the delivery mode and protects the endpoints using HTTP Basic Authentication.
No single sign-on is implemented between the front-end and back-end, so that multiple logons are necessary in case of access.

ONLY_AUTHN

This mode can only be used in conjunction with the security.manager.
It implements a domain cookie based access and thus supports Single Sign-On between the components.

The security settings can be enabled as follows:

#
#### security for smart.finder server web application
#

# mode "NONE", "INTEGRATED" (default) or "ONLY_AUTHN"
security.mode=INTEGRATED

# Admin user definition
security.user.admin.name=admin
security.user.admin.pw=admin
security.user.admin.roles=solrAdmin
# Password encoding
# plain|MD5|SHA-1
security.user.pwenc=plain
# must be true if 'plain' is not used in property security.user.pwenc
security.user.use_mapped_pass=false
# enable the login audit logging (works if security.mode != NONE)
security.user.login.log=true

# Additionally, the following properties are required for "ONLY_AUTHN"
security.administration.url=${security.administration.base.url}
security.was.service.url=${security.administration.url}/WAS
security.pdp.service.url=${security.administration.url}/PDP
security.sso.service.url=${security.administration.url}/resources/ssosessions
security.sso.token.service.url=${security.administration.url}/token/ssosession
security.login.service.url=/account/login

security.sso.cookie.name=${security.sso.cookie.name}
security.sso.cookie.domain=${security.sso.cookie.domain}
security.sso.cookie.bindToIP=false
security.sso.self.endpoint=${security.administration.url}/account/self

# Key Store Properties
security.keystore.location=${security.keystore.location}
security.keystore.passwd=${security.keystore.passwd}
security.keystore.key.alias=${security.keystore.key.alias}
security.keystore.key.passwd=${security.keystore.key.passwd}

The following values of the properties must be set according to their environment:

security.administration.base.url

URL to the /administration web application of the security.manager.

security.keystore.location

Path to the keystore file that contains the key pair for validating and generating digital signatures.

security.keystore.passwd

Password for access to the keystore.

security.keystore.key.alias

Alias of the certificate or private key.

security.keystore.key.passwd

Password for access to the private key.

security.sso.cookie.name

Name of the cookie that is used for the domain-wide single sign-on.

security.sso.cookie.domain

Name of the domain where the single sign-on cookie is valid. It must not start with a dot and must comply with the rules in RFC 6265.
Examples:

 example.com
 subdomain.example.net

TLS/SSL Server Trust

When establishing connections to HTTPS endpoints through server-side Java components, make sure that the TLS/SSL server certificate of the requested host is accepted and trusted by the Java Virtual Machine (JVM). Otherwise, no HTTPS connection to the server is established, and the application responds incorrectly. This affects the smart.finder when you use job configuration in the manager to index sources that are accessed via an HTTPS endpoint (e.g. OGC CSW catalog).

The configuration option security.ssl.trustAny controls under which conditions a TLS server certificate is accepted:

security.ssl.trustAny=true

All certificates are accepted.
The only condition is that the certificate is valid for a certain period of time. The certificate does not have to be issued for the requested host or by a trusted authority. This setting should only be active in development environments.

security.ssl.trustAny=false

(delivery status)
Only certificates that are considered trustworthy by the JVM are accepted.
It is strongly recommended to keep this setting. This is especially true for productive environments. You must ensure that server certificates of HTTPS endpoints to which connections are made are trusted. Otherwise, an error will occur when a connection is established.

Trustworthiness of server certificates

For a server certificate to be considered trustworthy by the JVM, you must install either the concrete server certificate or its root certificate in the Java Runtime Environment (JRE). Trusted certificates or root certificates are stored by default in the JRE in a Java keystore under [JRE_HOME]/lib/security/cacerts. However, depending on the operating system or configuration of the JVM, it is possible that other sources for trusted certificates are used.

The following section describes which types of server certificates are usually used by HTTPS endpoints and what needs to be considered with regard to trustworthiness.

Certificates with root certificate installed in the JRE

Productive Websites that provide services over HTTPS typically have server certificates whose root certificate is issued by a trusted Certificate Authority (CA). These root certificates are pre-installed in the JRE and are therefore automatically classified as trustworthy.

No further steps are required to allow connection to an endpoint whose server certificate has a root certificate already installed in the JRE.

Certificates with a root certificate that is not installed in the JRE

Occasionally, organizations use server certificates issued by their own internal CA. The corresponding root certificate is therefore not part of the certificates pre-installed in the JRE. Connections to HTTPS endpoints with such server certificates will fail unless the root certificate is automatically added to all JRE installations by internal company processes.

To ensure that all server certificates issued by this internal CA are trusted, the CA’s root certificate must be added to the keystore [JRE_HOME]/lib/security/cacerts.

Self-signed certificates

Self-signed server certificates, i.e. certificates that reference themselves as issuers, are often used for testing purposes and should not be used in production systems. Since a self-signed server certificate is not part of the certificates already installed in the JRE, it is not trustworthy.

To allow HTTPS connections to a host that uses a self-signed server certificate, add this certificate to the [JRE_HOME]/lib/security/cacerts keystore.

Typical error messages

When establishing server-side HTTPS connections, various error situations can occur in connection with the validation of server certificates. The following sections list typical error messages that may appear in the log file of the server-side application or in the browser interfaces of the applications. In addition, possible causes are described and solutions are suggested. Depending on the specific infrastructure in which the affected application is operated, other causes and solutions may also need to be considered.

Typical error messages:

PKIX path building failed

Complete error message:

sun.security.validator.ValidatorException:
PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

This error message is an indication that the certificate presented by the server for the HTTPS connection is not considered trustworthy by the JVM. It may be a self-signed certificate or the root certificate is not installed in the JRE.

Possible solutions:

  • Installing the root certificate in the JRE

  • Installing the server certificate in the JRE

  • If the requested server is under its own control: Provision of a new server certificate on the requested server, issued by a trusted CA.

No name matching [requested.host.name] found

Complete error message:

javax.net.ssl.SSLHandshakeException:
java.security.cert.CertificateException: No name matching maps.example.com found

This error message indicates that the host name used in the HTTPS request does not match the host name specified in the server certificate. The client (browser, Java application) compares the host name used in the request URL with the CN name of the Subject field in the server’s X509 certificate, for example

https://maps.example.com/

with

CN = www.example.com, O = Example LLC, L = Mountain Dew, ST = California, C = US.

If the two names do not match (upper/lower case is not relevant), the connection is terminated with the error message mentioned above. It is irrelevant whether the certificate would be classified as trustworthy. The trustworthiness check only takes place when it is ensured that the host names match.

This problem often occurs when clients can address the same server with different names because there are several DNS entries. Especially if the client is in the same domain as the server, the inconsistent use of non-qualified and fully qualified host names in request URLs or server certificates often leads to this problem. The use of the special host name localhost or IP addresses in URLs also causes this problem if the server certificate is issued to the qualified host name.

Possible solutions:

  • Use the host name in request URLs in the form specified in the server certificate.

  • Create and store a new server certificate for the host name requested by the client, for example, if it turns out that using a non fully qualified host name (or localhost or IP address) is not appropriate.

  • Create and store a new server certificate with alternative host names ("Subject Alternative DNS Names"), if it becomes clear, for example, that the server must inevitably be accessible under different host names.

No subject alternative DNS name [requested.host.name] found

Complete error message:

javax.net.ssl.SSLHandshakeException:
java.security.cert.CertificateException: No subject alternative DNS name matching maps.example.com found

This error message is a special case of the error message No name matching [requested.host.name] found. The only difference is that the server certificate has an additional field with alternative host names, but the host name used by the client does not match the Subject CN of the server certificate nor is it specified in its list of alternative host names (Subject Alternative DNS Names).

Possible solutions: The solutions suggested in the previous error message also apply here.

Indexable resources

smart.finder can index a number of different resources and thus make them searchable. In doing so, smart.finder automatically recognizes how a resource needs to be indexed. Therefore, no resource type or similar needs to be specified for indexing to be carried out correctly.

The following section provides an overview of the resource types that can be indexed. It also describes how the contents are indexed.

File based resources

The types listed in this table can be accessed either in the file system or via a URL. This means that http://example.com/file.ppt will produce the same index result as c:\file.ppt (assuming that file.ppt is identical in both cases).

Filename extension Name Indexed contents

doc

Microsoft Word 97-2003 Document

Complete Content

docx

Microsoft Word Document

Complete Content

geotiff

GeoTiff file

name + room section + specific metadata

html/xhtml

Hypertext Markup Language

Complete Text

jpg, png, gif

image files

path + file name

pdf

Adobe Acrobat Document

Complete content including metadata

ppt

Microsoft PowerPoint 97-2003 Presentation

Complete Content

pptx

Microsoft PowerPoint Presentation

Complete Content

rtf

Rich Text Format

Complete Content

shp

ESRI Shape file

name
room section, if .prj file exists
number of features
attribute names

txt

plain text

complete text

xls

Microsoft Excel 97-2003 Worksheet

Complete Content

xlsx

Microsoft Excel Worksheet

Complete Content

xml

XML

Complete content

Web services

Name Indexed contents Dedicated mapping file

OGC Catalog Service for the Web 2.0.2, ISO Application profile

Selected fields

jar:file:/ct-finder-api-2.5.1.jar!/de/conterra/finder/tika/xslt/iso19139.xslt

OGC Catalog Service for the Web 2.0.2, Capabilities

Selected Fields

jar:file:/ct-finder-api-2.5.1.jar!/de/conterra/finder/tika/xslt/csw.xslt

INSPIRE Discovery Service

Selected Fields

jar:file:/ct-finder-api-2.5.1.jar!/de/conterra/finder/tika/xslt/iso19139.xslt

INSPIRE Discovery Service, Capabilities

Selected Fields

jar:file:/ct-finder-api-2.5.1.jar!/de/conterra/finder/tika/xslt/csw.xslt

OGC Web Mapping Service 1.1.0 and 1.3.0 Capabilities

Selected Fields

jar:file:/ct-finder-api-2.5.1.jar!/de/conterra/finder/tika/xslt/wms.xslt

INSPIRE View Service Capabilities

Selected Fields

jar:file:/ct-finder-api-2.5.1.jar!/de/conterra/finder/tika/xslt/wms.xslt

ESRI ArcGIS Server REST Endpoint

Complete Content

internal

For indexing via an ESRI ArcGIS Server REST Endpoint, activate the Services Directory in the ArcGIS Server settings.