Installation & Upgrade Guide (Linux)

28/04/2025

Our new installer now embraces a modern, flexible approach using environment variables allowing you to manage all configuration settings in a single .env file - a change that brings two key benefits. It enables seamless integration with pipelines as well as automated deployments and simplifies the installation process by allowing all settings to be exported, prepared, and modified in advance.

For your convenience we have grouped the description into environment variables, preparation, installation & upgrade, and post-installation tasks.

We recommend collecting all mandatory details which you will need later during the installation. You will have to collect some important data on the target system as these details can be simply retrieved from the existing correctly configured setup.

Some basic mandatory target system details will be required during the installation procedure. Here is an example of mandatory parameters required for installation on a target system running a 64bit Linux distribution.

Our example uses example values - {url.base.scheme} for creating ontologies and custom schemes, for instance scheme.server.com; {url.base.vocabulary} for creating taxonomies, for instance vocabulary.server.com; {url.base.context} for named graphs, e.g. data.server.com; and {url.base.user} - the base URI for creating users, for instance resource.server.com/user

ENV_PATH_POOLPARTY_INSTALLATION="/opt/poolparty"
ENV_PATH_POOLPARTY_DATA="/opt/poolparty/data"
ENV_USER="poolparty"
ENV_GROUP="poolparty"
ENV_URL_POOLPARTY_BASE_SCHEME="https://scheme.server.com"
ENV_URL_POOLPARTY_BASE_VOCABULARY="https://vocabulary.server.com"
ENV_URL_POOLPARTY_BASE_CONTEXT="https://data.server.com"
ENV_URL_POOLPARTY_BASE_USER="https://resource.server.com/user"
ENV_PORT_POOLPARTY_TOMCAT="8081"
ENV_URL_KEYCLOAK="https://server.com:8181/auth"

The ENVs - or environment variables - help to automate the installation procedure. If you have a correct set of environment variables from your previous installation, you can export those and reuse them for any new installation. The table below lists all the ENV variables along with their default values.

Table 3. ENV variables used to automate the installation process

Mandatory to set	Example value	Remarks
`ENV_PATH_POOLPARTY_INSTALLATION`	`/opt/poolparty`	target directory should be empty on fresh installation
`ENV_PATH_POOLPARTY_DATA`	`/opt/poolparty/data`	target directory should be empty on fresh installation
`ENV_USER`	`poolparty`	has to exist in the system
`ENV_GROUP`	`poolparty`	has to exist in the system
`ENV_URL_POOLPARTY_BASE_SCHEME`	`http://localhost:8081`
`ENV_URL_POOLPARTY_BASE_VOCABULARY`	`http://localhost:8081`
`ENV_URL_POOLPARTY_BASE_CONTEXT`	`http://localhost:8081`
`ENV_URL_POOLPARTY_BASE_USER`	`http://localhost:8081/user`
`ENV_URL_KEYCLOAK`	`http://localhost:8081/auth`
`ENV_PORT_POOLPARTY_TOMCAT`	`8081`

There are few tasks you have to complete before you will be ready to install PoolParty.

You have to stop the PoolParty application. To do so switch to poolparty user and execute the stop command from the ENV_PATH_POOLPARTY_INSTALLATION/bin folder.
```
./poolparty stop
```
Make sure that no other PoolParty related process is currently running using the command below:
```
ps aux | grep java
```
The installation folder should be empty or not set up yet as the installer will create all required directories.

Now select the section covering the task you need to perform - if it is a fresh installation open the collapsed description with a click on the first topic below, for details on how to update an existing instance of PoolParty click the second link to view the collapsed description of the upgrade process.

Unpack the {compressed_PoolParty_file_name}.tar.gz file. Unpacking this file will create a folder called ENV_PATH_POOLPARTY_INSTALLATION/poolparty_setup containing all required files.
```
tar -xf {compressed_PoolParty_file_name}.tar.gz
```

Change the directory.
```
cd poolparty_setup
```

Now you will fine tune the .env file to match your target server configuration. Remember to adjust non-mandatory parameters if this is required for a certain component.

We are using the the vi editor to modify the .env file content:

vi .env

Example of the .env file for an on-premise installation on a Linux server

poolparty@/opt/poolparty/poolparty_setup$ cat .env 
ENV_PATH_POOLPARTY_INSTALLATION="/opt/poolparty"
ENV_PATH_POOLPARTY_DATA="/opt/poolparty/data"
ENV_USER="poolparty"
ENV_GROUP="poolparty"
ENV_URL_POOLPARTY_BASE_SCHEME="httpscheme.server.com”
ENV_URL_POOLPARTY_BASE_VOCABULARY="vocabulary.server.com"
ENV_URL_POOLPARTY_BASE_CONTEXT="data.server.com"
ENV_URL_POOLPARTY_BASE_USER="resource.server.com/user"
ENV_PORT_POOLPARTY_TOMCAT="8081"
ENV_URL_KEYCLOAK="server.com/auth"

Start the installation.

Run the .setup.sh script.
```
./setup.sh
```
If all the mandatory variables set in the .env file were correct, installation will complete without any interaction from you.
Note
If this file contains an error or a typo for instance, the installation will be aborted. To see why the installation process has been aborted open the log file where you find all the respective details required to make any corrections to the respective entry in the .env file.

After successful completion of the installation process you will see all the credentials printed on the screen:

/opt/poolparty/poolparty_setup$ ./setup.sh
[ Note ] PoolParty installation script for version 9.5.0 has started.
[ Note ] Input validation and system checks have been completed.
[ Note ] Files and folders have been copied to the specified target directories.
[ Note ] Placeholder values in configuration files have been updated with the provided input (.env file).
[ Note ] Keycloak has been successfully set up.
[ Note ] Elasticsearch has been successfully set up.

[ Note ] Authentication service admin credentials: poolparty_auth_admin/password
[ Note ] Superadmin credentials: superadmin/password 
[ Note ] Elasticsearch credentials: elastic/password

[ Note ] Running PoolParty with root user privileges is not recommended.

The installation logs are located in the following directory: ENV_PATH_POOLPARTY_INSTALLATION/poolparty_setup/pp-installation.log.

Then obtain the PoolParty license file and add it to the license directory {repository.server}/config/licenses. The default setting for the license directory is ENV_PATH_POOLPARTY_INSTALLATION/config/licenses.

Unpack the {compressed_PoolParty_file_name}.tar.gz file. Unpacking this file will create a folder called ENV_PATH_POOLPARTY_INSTALLATION/poolparty_setup containing all required files.
```
tar -xf PoolParty_Integrator_9.5.0.tar.gz 
```

Check and when required edit the variables in the .env file located in the /poolparty_setup/ directory.

Example of the .env file for an on-premise installation upgrade on a Linux server

ENV_PATH_POOLPARTY_INSTALLATION="/opt/poolparty"
ENV_PATH_POOLPARTY_DATA="/opt/poolparty/data"
ENV_USER="poolparty"
ENV_GROUP="poolparty"
ENV_URL_POOLPARTY_BASE_SCHEME="<scheme.server.com>"
ENV_URL_POOLPARTY_BASE_VOCABULARY="<vocabulary.server.com>"
ENV_URL_POOLPARTY_BASE_CONTEXT="<data.server.com>"
ENV_URL_POOLPARTY_BASE_USER="<resource.server.com>/user"
ENV_PORT_POOLPARTY_TOMCAT="8081"
ENV_URL_KEYCLOAK="<server.com>:8181/auth"

Then go to the ENV_PATH_POOLPARTY_INSTALLATION/poolparty_setup/ directory and start the upgrade by running the ./setup.sh script.

When updating a PoolParty instance it is sufficient to set the ENV_PATH_POOLPARTY_INSTALLATION variable since the other mandatory variables set in the .env file should be correct. When all these variables are correctly set the installation will complete without any interaction from you.
Note
If this file contains an error or a typo for instance, the installation will be aborted. To see why the installation process has been aborted open the log file where you find all the respective details required to make any corrections to the respective entry in the .env file.

After successful completion of the upgrade process you will see all the credentials printed on the screen:

/opt/poolparty/poolparty_setup$ ./setup.sh
[ Note ] PoolParty installation script for version 9.5.0 has started.
[ Note ] The upgrade process has been initialized.
[ Note ] The Tomcat update has been successfully completed.
[ Note ] The Elasticsearch update has been successfully completed.
[ Note ] The Keycloak update has been successfully completed.
[ Note ] PoolParty was updated from 9.4.3 to 9.5.0

[ Note ] Running PoolParty with root user privileges is not recommended.

The installation logs are located in the following directory: ENV_PATH_POOLPARTY_INSTALLATION/poolparty_setup/pp-installation.log.

Normally, you will not have to provide the license when updating your PoolParty instance. If however you are granted a new license file, then add it to the license directory located at ENV_PATH_POOLPARTY_INSTALLATION/config/licenses.

Start the PoolParty by executing the start command from the ENV_PATH_POOLPARTY_INSTALLATION/bin folder.
```
./poolparty start
```

Check that the application is up.

tail -f /opt/poolparty/tomcat/logs/catalina.out

The following should appear at the end of the log:

INFO [main] org.apache.catalina.startup.Catalina.start Server startup in [121433] milliseconds

If everything is fine, you can delete the PoolParty installation files from the poolparty_setup directory and the *.tar installer.
Tip
It is recommendable to keep a copy of the .env file for reference.

In this section: