Skip to main content

Migration Steps for UnifiedViews

01/06/2026

The migration of UnifiedViews from a native installation to a Dockerized environment is a manual process. It involves migrating configuration files, RDF4J data, and working directories to the new containerized architecture. UnifiedViews is released with Docker files and Helm charts designed for Kubernetes deployment, starting with UnifiedViews version 10.2.0.

Note

The shellDPU is excluded from the standard distribution for security reasons. It is only provided to clients who have signed a liability waiver. Contact your Graphwise representative to obtain this implementation.

Migration steps

  1. Ensure the old UnifiedViews is fully stopped.

  2. Inspect the pp10-rdf4j-1 container to determine the configured user (e.g., tomcat).

    docker inspect pp10-rdf4j-1 --format 'User={{.Config.User}}'

  3. Stop the new UnifiedViews (both rdf4j and unified-views services).

    docker compose -f docker-compose.yaml -f addons.yaml down rdf4j unified-views

  4. You cannot use the old unifiedviews.properties file directly. Update your old file with the following container-specific paths:

    module.path = /unified-views/dependencies
general.workingdir = /unified-views/data/backend/working
frontend.log.directory = /unified-views/logs/frontend
backend.log.directory = /unified-views/logs/backend

    You may also check the default uv.properties file (see Prerequisites, step 4) for reference.

  5. In addons.yaml, map your adapted properties file to the container:

    volumes:
      -./unifiedviews.properties:/unified-views/configs/uv.properties

  6. Delete the default content in the rdf4j_data volume to prepare for legacy data:

    docker run --rm \
      -v pp10_rdf4j_data:/data \
      alpine sh -lc 'rm -rf /data/* /data/.[!.]* /data/..?* || true; ls -la /data'   

  7. Inspect the RDF4J workbench image and get the value of user identity:

    docker run --rm --entrypoint sh eclipse/rdf4j-workbench:4.3.15 -lc 'id; echo "---"; id tomcat || true'

    Example output: uid=101(tomcat) gid=65534(nogroup) groups=65534(nogroup)

  8. Copy the legacy server folder itself and its content to the volume and apply permissions (Example using 101:65534).

    docker run --rm \
      -v pp10_rdf4j_data:/data \
      -v "$PWD/uv_rdf4j":/src:ro \
      alpine sh -lc \
      'cp -a /src/. /data/ && \
      chown -R 101:65534 /data/server && \
      chmod -R 750 /data/server'

    Before starting the service at step (10), check the content of the /data/server folder inside the volume, it should contain old RDF4J content.

    Expected:

    docker inspect rdf4j_data
~
"Mountpoint": "/rdf4j_data/_data"
~

cd /rdf4j_data/_data/server

ls -l
total 0
drwxr-x--- 2 sshd nogroup 87 Aug 23  2023 conf
drwxr-x--- 2 sshd nogroup 76 May  6 14:42 logs
drwxr-x--- 3 sshd nogroup 16 Aug 23  2023 repositories

  9. Start the services:

    docker compose -f docker-compose.yaml -f addons.yaml up -d rdf4j unified-views
Remarks

  1. DPUs customized in the old environment are not migrated automatically. You must manually import them via the UI. Ensure these DPUs are compatible with the new UnifiedViews version.

  2. The new installation will continue to use the working folder from the old instance. To maintain consistency, you may map the container location (/unified-views/data/backend/working) to your external backup volume.

  3. After verifying the migration, you may re-enable OIDC to allow external user authentication.

  4. Pipelines and DPUs can be managed via API calls, which support both Basic Auth and OAuth (when OIDC is enabled). More details on API usage can be found on the Swagger OpenAPI documentation page.

    Used DPUs in pipelines can be exported together within the pipeline(s) export (see below).

  5. Swagger API Documentation is disabled by default. To enable it, set master.api.doc.enabled = true in the properties file and restart the service.

    Swagger URL: http(s)://<server-name>/master/swagger-ui/

  6. If you need to retrieve the default DPUs initialized during the first start, they are located inside the container at: /unified-views/dependencies/defaultdpus.

Examples of API calls

Export of all pipelines (pipelines + all DPUs used in pipelines):

          curl --location 'https://<server-name>/master/api/1/pipelines/export?asUser=admin' \
          --header 'Content-Type: application/json' \
          --header 'Accept: application/zip' \
          --header 'Authorization: Basic YWRtaW46dW5pZmllZHZpZXdz' \
          --data '{
          "exportDPUUserData": true,
          "exportJars": true,
          "chbExportSchedule": true
          }' \
          -o pipelines.zip

Export of a single pipeline (pipeline + all DPUs used in the pipeline):

          BASE_URL="https://<server-name>/master/api/1"
          PIPELINE_ID="ef385338-f370-402b-9b40-4c6b9a68645b"
          AUTH_B64="YWRtaW46dW5pZmllZHZpZXdz"
          curl --location "$BASE_URL/pipelines/$PIPELINE_ID/export" \
          --header 'Content-Type: application/json' \
          --header 'Accept: application/zip' \
          --header "Authorization: Basic $AUTH_B64" \
          --data '{
          "exportDPUUserData": true,
          "exportJars": true,
          "chbExportSchedule": true
          }' \
          -o "pipeline-$PIPELINE_ID.zip" \
	  -w "\nPIPELINE_ID: $PIPELINE_ID\nHTTP status: %{http_code}\n"

Export of a single pipeline import:

	  
          curl --location 'https://<server-name>/master/api/1/pipelines/import' \
          --header 'Authorization: Basic YWRtaW46dW5pZmllZHZpZXdz' \
          --form 'file=@pipeline.zip' \
          --form 'asUser=admin' \
          --form 'importUserData=true' \
          --form 'importSchedule=true' \
	  -w '\nHTTP status: %{http_code}\n'
Rollback procedures

Stop the Docker container and start your previous UnifiedViews installation.

In this section: