Skip to main content

Install the PoolParty Application Development Framework

You can install the PoolParty Application Development Framework (ADF) as a standalone application or as an application that shares an Apache Tomcat instance with PoolParty. Currently the application can only run on a Linux system.

Prerequisites

The following prerequisites must be satisfied before you start with the installation procedure:

. System Requirements

  • 64bit GNU/Linux Server (CentOS/RHEL/Oracle Linux 7 and 8)

  • at least 5 GB free disk space and 4 GB RAM

. Software Requirements

  • PoolParty Thesaurus Server 9.1 (PoolParty 2022 Release 2) or higher

  • OpenJDK (same version as currently installed for your PoolParty instance), make sure that JAVA_HOME is set up properly

  • Keycloak (is shipped with PoolParty; during the installation, you will be prompted to provide its URL, name of the PoolParty realm and a client secret for the client ppt)

  • Apache Tomcat 9 (you can install ADF with its own Tomcat instance or as an application that shares an Apache Tomcat instance with PoolParty)

Installation Procedure

Example 1. Example Installation Routine
This will install ADF 1.2.0 on your computer. 1 
OK [o, Enter], Cancel [c]
> o

Choose the appropriate option: 2
Install ADF [1, Enter],
Upgrade an existing ADF installation [2],
Cancel installation [c]
> 

Choose the appropriate option: 3
ADF is run as a standalone application [1, Enter],
ADF is run on a shared Tomcat 9 instance (this will not update Tomcat) [2],
Cancel installation [c]
> 1

Where should ADF be installed 4
[/opt/ADF]
>

Default ADF user: 5
[poolparty]
>

Default ADF group: 
[poolparty]
>

Please review: 6
SETTING                 VALUE
Installation directory  /opt/ADF, Access: OK
ADF user:group          poolparty:poolparty

Proceed installation?
OK [o, Enter], Cancel [c]
>

Which base path (directory in the URL) do you want ADF to be accessible at? (e.g.: /ADF) 7
> /search

What is the URL to the PoolParty instance to use? (e.g.: https://test.poolparty.biz) 8
> https://example.poolparty.biz

What is the user group for the PoolParty user? 9
> ADF

What is the URL to the Keycloak instance to use? (e.g. https://<KEYCLOAK_URL>[:8181]) 10
> https://example-keycloak.poolparty.biz:8181


What is the Realm in the Keycloak instance to use? (e.g. poolparty) 11
> poolparty


What is the Client Secret of Keycloak Client "ppt"? 12
> JhbGciOiJSUzI1NiIsInR5

Please review the application properties: 13


SETTING                 VALUE
PoolParty URL           https://example.poolparty.biz
PoolParty User          superadmin
PoolParty User Group    ADF
Keycloak URL            uhttps://example-keycloak.poolparty.biz:8181
Keycloak Realm          poolparty
Keycloak Client ID      ppt
Keycloak Client Secret  JhbGciOiJSUzI1NiIsInR5
Proceed installation?
OK [o, Enter], Cancel [c]
>


1

Download the ADF installer (for example ADF_1.2.0.run) from the SWC download area and run it from the terminal. When prompted that ADF will be installed on your system, confirm by pressing either o or Enter.

Caution

Run the installer as a root user to ensure smooth installation process and avoid any permission issues during the installation procedure.

2

When prompted about the installation options, select a fresh installation by entering 1 or pressing Enter.

3

Specify whether you want to install ADF as a standalone application (i.e. with its own Tomcat 9 instance) by pressing 1 or Enter or as an application that shares an Apache Tomcat instance with PoolParty by pressing 2.

4

Specify the folder where ADF should be installed or confirm the default path by pressing Enter.

5

Specify the default user and group under which ADF will run.

6

Review the settings you have just made. If everything is correct, proceed with the installation by pressing o or Enter. If you want to change the settings, press c.

7

Enter the base path where ADF will be accessible at starting with a slash.

For instance if you specify /search as a base path, the main user interface will be accessible at servername/search and the configuration interface at servername/search/configurations.

8

Enter the URL of the PoolParty instance that ADF will work on top of. The API calls to PoolParty are protected with OAuth 2.0

9

Specify the PoolParty user group that will permit access to the areas in ADF that are protected with authentication. Only users who are members of this PoolParty group will be able to log in to the ADF configuration interface and access the configurations on the main user interface that require login.

Tip

If you want to give all PoolParty users access to all ADF areas protected with authentication, use the user group Public.

10

Enter the URL of PoolParty's Keycloak instance.

11

Specify the realm in Keycloak for the connected PoolParty instance.

12

Specify the client secret of the Keycloak client ppt.

13

Review the application settings. If everything is correct, confirm with o or Enter. If you want to change the settings, press c.

Procedure. Post-Installation Tasks

  1. Make sure that Keycloak and Apache Tomcat are up and running. Their default ports are:

    • Apache Tomcat: 8080

    • Keycloak: 8181

    If you have installed ADF with a separate Apache Tomcat 9 instance, you need to start Tomcat manually using a startup.sh script.

    # ./startup.sh
ROOT-SURFACE:           /opt/recommenderworkbench/bin
using CATALINA_BASE:    /opt/recommenderworkbench
using CATALINA_HOME:    /opt/recommenderworkbench
using CATALINA_TMPDIR:  /opt/recommenderworkbench/temp
using JRE_HOME:         /usr
using CLASPATH:         /opt/recommenderworkbench/bin/boostrap.jar:/opt/
recommenderworkben/bin/tomcat-9.jar
using CATALINA_OPTS:    
Tomcat started.

  2. Open a browser and access the ADF installation at localhost:8080/basepath/ to verify that everything works as expected.

    Note

    After successful installation of the Application Development Framework (ADF), the ADF.properties file is created at the following path: opt/ADF/WEB-INF/classes.

    The file contains the configuration options you specified during the installation or upgrade process together with default settings relevant to your ADF installation such as database and logging configuration. For more information, refer to Administering the ADF Server with the ADF.properties File.

In this section: