Key Survey application setup and configuration

1. Application Setup

Before you proceed with application files setup, make sure that JRE or JDK 11 is already installed on the APP host, where you are going to install Key Survey Application. You can download new installer from Oracle (requires license agreement)

https://www.oracle.com/technetwork/java/javase/downloads/jdk11-downloads-5066655.html or any latest build of open source Java 11.

Below you will find an example of OpenJDK installation, where https://download.java.net/java/GA/jdk11/9/GPL/openjdk-11.0.2_windows-x64_bin.zip build is used. Replace links and version number with the Java build you are using:

• Extract jdk-11.0.2 folder from the archive to C:\Program Files\Java, so new Java folder on the app server is C:\Program Files\Java\jdk-11.0.2

• Click Start/Windows button, search for System environment variable and click ‘Edit the system environment variables’;

• Go to ‘Advanced’ tab and click ‘Environment Variables’ button • Find ‘JAVA_HOME’ in System Variables section and click Edit;

• Update ‘Variable Value’ box with the path where Java 11 is installed (for example C:\Program Files\Java\jdk-11.0.2) and save your changes.

• If there is no ‘JAVA_HOME’ in System Variables section just click Create and setup: Variable name: ‘JAVA_HOME’, Variable value: ‘C:\Program Files\Java\jdk-11.0.2’

a. Create 'c:\hosting' directory, where the application will be installed.

b. Extract 'keysurvey_app\keysurvey-standalone.zip' file from the Key Survey installation package folder into the 'c:\hosting\' directory. Folder 'keysurvey-standalone' should appear in the 'c:\hosting\' directory.

1.1 Enable secure mode.

Tomcat of Key Survey installation has to be configured to handle HTTPS traffic.

This can be done following the instructions from Apache Tomcat official site:

http://tomcat.apache.org/tomcat-9.0-doc/ssl-howto.html

All needed settings in 'server.xml' file mentioned in Tomcat documentation have to be applied to the 'c:\hosting\keysurvey-standalone\conf\server.xml' file of Key Survey installation.

Key Survey should be configured to work with HTTPS links. This can be accomplished by adjusting parameters in 'c:\hosting\keysurvey-standalone\keysurvey\config.properties' file.

SECURE_URL_PATH.SURVEY=https://www.yourkeysurvey.com:8443/

Replace 'www.yourkeysurvey.com' with the address of your Key Survey site. '8443' is the default Tomcat HTTPS port.

To improve security, turn on redirection to secure connection on admin pages. Change the value of 'ALLOW_SECURE_LOGIN.SURVEY' to 'true' in keysurvey/config.properties':

ALLOW_SECURE_LOGIN.SURVEY=true

1.2 Enable HTTP ports.

1. Using Microsoft Management Console stop Tomcat service if it is running.

2. In 'c:\hosting\keysurvey-standalone\keysurvey\config.properties' file remove port numbers from URL related settings:

URL_PATH.SURVEY=http://www.yourkeysurvey.com/
SECURE_URL_PATH.SURVEY=https://www.yourkeysurvey.com/

Replace 'www.yourkeysurvey.com' with the address of your Key Survey site.

In 'c:\hosting\keysurvey-standalone\conf\server.xml', edit HTTP connector settings to listen on port 80 instead of default 8080.

The edited block will look like this:

<Connector port="80" protocol="HTTP/1.1"
     redirectPort="8443"
     maxThreads="1000"
     URIEncoding="UTF-8" />

If you have configured Tomcat to work over HTTPS on port 443 then in 'c:\hosting\keysurvey-standalone\conf\server.xml', edit SSL HTTP connector settings to listen on port 443 instead of default 8443.

The edited block will look like this:

<Connector port="443" protocol="HTTP/1.1"  
     SSLEnabled="true"
     maxThreads="1000"
     scheme="https" secure="true"
     clientAuth="false" sslProtocol="TLS" />

Start Tomcat service.

Now you can access the Key Survey site in the browser via the site address without port numbers.

2. Application Configuration

a. Edit the 'c:\hosting\keysurvey-standalone\keysurvey\config.properties' file using tips in the comments. Comments and examples are prefixed by '#' character at the beginning of the line. All the parameter values enclosed into angle brackets '<>' should be replaced with the values appropriate to your site. Angle brackets should be removed.

'DB_CONNECTION', 'DB_LOGIN' and 'DB_PASSWORD' values should be set using DB host, DB name, DB credentials values that have been configured during the database setup in Section 2. Note that ‘DB SESSION’ and ‘DB ADDITIONAL INFO’ sections should include the same DB connection, login and password parameters.

b. Edit 'c:\hosting\keysurvey-standalone\keysurvey\application.yml' configuration file and replace all , , , . These should be the same parameters you used in the config.properties file for DB connection.

Replace with the same value you have specified in services.client.authentication.clientSecret= parameter in config.properties file.

c. Run 'c:\hosting\keysurvey-standalone\bin\service.bat install Tomcat9' to register Tomcat 9 service and run 'c:\hosting\keysurvey-standalone\bin\setenv.bat'.

To verify the service was installed successfully, run Start->Administrative Tools->Services. You should see 'Apache Tomcat 9' service in the list.

d. Run 'c:\hosting\keysurvey-standalone\bin\tomcat9w.exe' to set up Tomcat parameters.

Click on the 'Java' tab. Specify path to Java Virtual Machine, type ‘12288’ in the ‘Initial memory pool’ and ‘Maximum memory pool’ fields and click ‘Apply’.

e. Key Survey application has a number of password protected service pages. Default credentials for these pages are 'admin' and 'password'. It is highly recommended to change the default password in the file 'c:\hosting\keysurvey-standalone\conf\tomcatusers.xml'. You can change the password by editing the following line:

<user username="admin" password="password" 
roles="keysurveyadmin"/

3. Start Tomcat service.

On average it takes 5-10 minutes for application to start

You can review logs in 'c:\hosting\keysurvey-standalone\logs' directory. Log files may contain useful information for resolving any errors that may appear during start-up process or application work.

4. App is ready

Once the Key Survey application is started, you should use the link specified in the 'URL_PATH.SURVEY' parameter in the 'config.properties' file to access the Key Survey application in your browser.

At this point, you have the Key Survey site up and running. It is available via the internal server name or IP of your APP host or via the domain name you have configured for the site.

By default, with basic installation option, Key Survey site is available on TCP port 8080 – the default Tomcat HTTP port. Therefore, make sure Windows Firewall rule to access Key Survey application via port 8080 is enabled.

Appendix A. Additional Key Survey installation options