PoolParty 9.7 to 10 Migration Guide

25/09/2025

This guide provides a step-by-step process for migrating PoolParty 9 to PoolParty 10 using the official migration tool in a Docker Compose environment.

Note

This guide is partially based on the official migration tool's README.md file which can be downloaded here, together with the migration tool in a ZIP file. Please refer to the README.md as the ground truth, as updates to the public documentation may be comparatively slower.

Before beginning the migration, ensure the following conditions are met:

To migrate, your PoolParty instance needs to be at least version 9.7.x.
You have a clean GraphDB instance running.
You have a recent version of Docker and the docker-compose plugin.
You have downloaded the migration tool and the compose repository.
Any projects in PoolParty 9 that reside on a remote GraphDB instance must be exported beforehand, as they will not be automatically migrated.
The PoolParty 9 instance must be stopped.
Configure the POOLPARTY_9_DIR variable in your .env file to point to the installation directory of your PoolParty 9 instance.

The PoolParty 9 to 10 migration tool is a standalone command-line JAR file which can be obtained by downloading a released version. It is designed to safely read your PoolParty 9 installation, process the configuration and repositories, and write the migrated files to a new, specified directory. It can be run with java -jar poolparty-10-migration-1.0.0.jar <arguments>, for example.

The tool performs the following migrations:

The migration tool copies and modifies files and directories from the PoolParty 9 home directory (<from-dir>) to the PoolParty 10 home directory (<to-dir>).
Caution
Note that data/snapshotsRoot will not be copied and any existing snapshots will be lost. The data from data/sesameRoot and data/graphdb will not be copied; however they will be exported from the repositories and then imported into GraphDB. The folders data/elasticsearch and <pp9>/auth_service/keycloak/data will not be copied as they need to be handled separately as part of Elasticsearch and Keycloak data migration. This process is described in the step-by-step procedure below.
The poolparty.properties file is copied and updated with new configuration properties:
- The three separate CORS XML files (cors-config-extractor.xml, cors-config-graphsearch.xml, cors-config-thesaurus.xml) are converted into a single set of properties within the poolparty.properties file.
- New GraphDB, Keycloak, and Elasticsearch configuration properties will be added. These configurations can be skipped by using --disable-graphdb, --disable-keycloak, and --disable-elastic, respectively.
  Note
  From PoolParty 10.0 there will be only a single realm client required to be maintained in Keycloak, the ppt realm client. The other three Keycloak realm clients - i.e. ppx, ppgs, and recommender - used in previous PoolParty versions (e.g. PP 2025 R2) are from this point on integrated in the ppt realm client.
Both RDF4J and embedded GraphDB repositories from PoolParty 9 are exported and either imported into a remote GraphDB instance or stored locally for offline migration. Repository names are updated to the convention summarized in the table below, where each PoolParty 10 repository must start with the pp_ prefix.

PoolParty 9	PoolParty 10
`pptSystem`	`pp_system`
`users`	`pp_users`
`graphSearchSystemRepository`	`pp_graphSearch`
`customschemaRepository`	`pp_customSchema`
`corpusMetaInfoRepository`	`pp_corpusMetaInfo`
`corpusRepository_xxx`	`pp_corpus_xxx`
`graphsearch_xxx`	`pp_graphsearch_xxx`
`editorRepository_xxx`	`pp_editor_xxx`
`xxx`	`pp_project_xxx`

The migration tool is run on the command line using the following syntax:

java -jar poolparty-10-migration-<version>.jar [options] <from-dir> <to-dir>

Mandatory Arguments:

--gdb-url <url>: The URL(s) of the remote GraphDB instance.
<from-dir>: The path to the PoolParty 9 home directory.
<to-dir>: The path to the new PoolParty 10 home directory. The tool will create this directory, so it may not already exist or must be empty.

Common Options:

--gdb-username <username>: Username for GraphDB Basic authentication.
--gdb-password <password>: Password for GraphDB Basic authentication.
--skip-remote: Skips migration of projects on remote repositories.
--local-db <dir>: Exports repositories to a local directory instead of a remote GraphDB instance (offline mode).
--gdb-license <file>: The GraphDB license file, required for offline mode.
--env-file <file>: Writes the configuration for GraphDB, Keycloak, Elasticsearch and CORS as an .env file instead of poolparty.properties. This option allows you to write configurations in a format suitable for various container environments.
--yaml-file <file>: Write the configuration for GraphDB, Keycloak, Elasticsearch and CORS as an environment section of a YAML file instead of poolparty.properties. This option allows you to create a YAML configuration that is compatible with Docker Compose.
--dry-run: Runs a migration simulation without writing any files or data.

Tip

Run the tool without any arguments or with -h/--help to view a help message listing all arguments.

To ensure the migration process will succeed before a full run, use the --dry-run option. This will validate the tool's actions without making any changes to your files or remote GraphDB.

java -jar poolparty-10-migration-1.0.0.jar --dry-run [your other arguments]

This will print a summary of what the tool would do, and will still connect to the GraphDB to check for repository presence, providing an early warning of potential conflicts.

Note

The procedure described in this section is based on the Migrating from PoolParty 9.7 section in the Docker compose file for PoolParty README.md file, which can be found here. Please refer to the README.md as the ground truth, as updates to the public documentation may be comparatively slower.

The following step-by-step process simplifies the migration by centralizing all operations within a controlled Docker container environment. This process abstracts away the complexities of manual file system and Docker management, providing a unified and repeatable workflow that is consistent across different user environments.

This guide thereby assumes a container-based migration using a dedicated migration.yaml compose file. All migration steps will be executed within the PoolParty container. The migration.yaml file disables the Keycloak and Elasticsearch containers but ensures their volumes are created. It leaves GraphDB running so that project data can be migrated.

Run the following command to start the necessary containers for the migration process:
```
docker compose -f docker-compose.yaml -f migration.yaml up -d
```
Execute a shell inside the poolparty container with root privileges to perform the migration tasks:
```
docker compose -f docker-compose.yaml -f migration.yaml exec --user root -it poolparty bash
```
To migrate all local projects and PoolParty configurations, run the following commands:
```
java -jar /migration/poolparty-10-migration-1.0.0.jar "/var/lib/poolparty-9" "/var/lib/poolparty" \
  --gdb-url http://graphdb:7200 \
  --skip-remote \
  --env-file /migration/env_migrated
chown -R poolparty:poolparty /var/lib/poolparty
```
This step migrates all repositories from PoolParty 9.7 to a new external GraphDB instance. If you are not using the GraphDB instance from the compose file, change the --gdb-url flag. You can also provide --gdb-username, --gdb-password for basic authentication, or --gdb-auth-header for other authentication methods.

Copy the Elasticsearch data from the old installation to the new volume:

cp -r /var/lib/poolparty-9/data/elasticsearch/. /usr/share/elasticsearch/data/
chown -R 1000:root /usr/share/elasticsearch/data

Migrate Keycloak data by choosing one of the following options, based on your setup:
1. If you used the embedded database in PoolParty 9.7 and want to use the embedded database in the new Keycloak instance, run:
```
cp -r /var/lib/poolparty-9/auth_service/keycloak/data/. /opt/keycloak/data/
chown -R 1000:root /opt/keycloak/data
```
2. If you used an external database in PoolParty 9.7 and want to use the same external database, add the appropriate Keycloak configurations in the .env file.
3. If you plan to use an external Keycloak instance, configure the PoolParty container to use that instance.
Exit the container using the exit command, and then stop the containers. Be careful not to delete the volumes.
```
exit
docker compose -f docker-compose.yaml -f migration.yaml down
```
In step 3, the --env-file /migration/env_migrated flag created the env_migrated file in the current working directory. Apply these migrated configurations as follows:
- Copy the contents of the env_migrated file and paste it at the end of your main .env file.
- Review the migrated configurations and ensure that any addresses match the new installation.
- Delete the POOLPARTY_INDEX_URL property, as it is already present in the configuration with the correct value.
Follow the official section on running the compose files to start your new PoolParty 10 instance. Then, import any previously downloaded remote projects back into PoolParty.

Note

This guide details the standard, online migration process, which directly imports data into a running GraphDB instance. If you need to perform an offline migration, the migration tool can save the GraphDB repositories to a local folder. These repositories must then be manually copied into an existing GraphDB instance's repositories directory or attached via Docker volumes. For specific command-line instructions, please refer to the sections on offline migration options in the migration tool's README.md.

In this section:

PoolParty 9.7 to 10 Migration Guide

Note

Caution

Note

Tip

Note

Note