Skip to main content
Pentaho Documentation

Upgrade Pentaho Servers and Design Tools

Explains how to update the BA and DI Servers as well as the Design Tools.

The upgrade process has been streamlined for Pentaho 6.0. To keep it simple, the process is similar whether you are installing the entire Pentaho Business Analytics (BA) suite or the Data Integration (DI) pieces only.

Upgrade the Pentaho Business Analytics Server

After you finish the prerequisite tasks located in Prepare Your Pentaho Server for Upgrade, there are five tasks that you will need to complete in order to upgrade to Pentaho 6.0 successfully.

These sections will guide you through the remaining steps of the Pentaho BA upgrade process:

  • Backup Your BA Server Configuration and Solutions Files
  • Install Pentaho Business Analytics 6.0
  • Restore Your BA Server Configuration and Solutions Files
  • Test Your BA Server
  • Update Your Pentaho BA Client Tools

Step 1: Backup Your BA Server Configuration and Solutions Files

The backup utility copies your Pentaho configuration and solutions files, then stores the created .zip files in your user's home directory. You will need to merge your customizations if you have previously customized any of these things: server.xml, startup and shutdown scripts, or system listeners. We recommend making complete backups of your Quartz, Hibernate, and Jackrabbit databases before continuing with the upgrade process.

  1. Stop the BA Server.
  2. Connect to the cmd line terminal for the BA Server.
  3. At the prompt, run the correct BAServerConfigAndSolutionsBackup utility for your operating system. 

    Windows

    BAServerConfigAndSolutionsBackup "C:\Program Files\pentaho\server\biserver-ee"
    

    Linux

    ./BAServerConfigAndSolutionsBackup.sh /opt/custom software/pentaho/server/biserver-ee
    

The next step is to install a new instance of the Pentaho 6.0 software. 

Step 2: Install Pentaho Business Analytics 6.0

A fresh archive installation of the Pentaho BA 6.0 package is needed as part of the upgrade process, after you have finished the upgrade prerequisites and backed up your Pentaho BA configuration and solutions files.  You'll need this in order to get all of the required updates.

Next, do these tasks from the Prepare Your Environment section of the archive installation guides. Make sure that you leave your Pentaho 5.x instance "as is" and unpack Pentaho 6.0 into a new directory. 

Windows

Linux

If you are using custom port numbers and a custom fully-qualified URL, there are some updates for 6.0 that you should be aware of. Change the Port Numbers for the BA Server has information and steps for how to do both of these things in Pentaho 6.0.

Step 3: Restore Your BA Server Configuration and Solutions Files

After you have unpacked your Pentaho 6.0 bundle, restore your Pentaho files to your 6.0 instance using the restore utility tool. 

If you do not wish to upload or replace your current sample data, it is recommended that you rename the files located in the pentaho-solutions/system/default-content directory prior to restarting the server. These files may include pentaho-operations-mart-etl, pentaho-operations-mart-operations, plugin-samples-zip, and samples-zip.

  1. Log in to your 6.0 BA Server and open a command prompt.
  2. In the prompt, run the BAServerConfigAndSolutionsRestore utility to restore your data from the .zip files located in your user home folder. 

    Windows

    BAServerConfigAndSolutionsRestore "C:\Program Files\pentaho\server\biserver-ee"
    

    Linux

    ./BAServerConfigAndSolutionsRestore.sh /opt/home/pentaho/server/biserver-ee
    
  1. Restart the BA Server

Step 4: Test Your BA Server

The last thing that you will need to do before testing is to clear the cache from your web browser. 

Here are some of the things that you might want to do to verify that your content has been restored to the BA Server:

  • Navigate to the your Pentaho URL and make sure the login screen appears.
  • Log into PUC and verify that you can run your old BA content.
  • Verify that your schedules exist and are working properly.
  • Make sure that your Pentaho plugins are installed and functional:
    • Open a report that requires no user prompts and a parameterized report.
    • Create a test report for Interactive Reporting and one for Analyzer, as appropriate.
    • Open a dashboard in Dashboard Designer.
    • Publish a report in Report Designer.
    • Publish an analysis schema from Spoon.
  • Check your application server log. 

Step 5: Update Your Pentaho BA Design Tools

The Pentaho BA design tools are stand-alone tools and are easily updated on your workstations. 

  1. Stop the design tool, if it is currently running.
  2. Move the old design tool out of the Pentaho folder structure to a temporary folder.
  3. Copy the new version of the design tool into the Pentaho folder structure.
  4. Restart your design tool.

Upgrade the Pentaho Data Integration Server

After you finish the prerequisite tasks located in Prepare Your Pentaho Server for Upgrade, there are five tasks that you will need to complete in order to upgrade to Pentaho 6.0 successfully.

These sections will guide you through the remaining steps of the Pentaho DI upgrade process:

  • Backup Your DI Server Configuration and Solutions Files
  • Install Pentaho Data Integration 6.0 
  • Restore Your DI Server Configuration and Solutions Files
  • Test Your DI Server
  • Update Your Pentaho DI Client Tool

Step 1: Backup Your DI Server Configuration and Solutions Files

The backup utility copies your Pentaho configuration and solutions files, then stores the created .zip files in your user's home directory. You will need to merge your customizations if you have previously customized any of these things: server.xml, startup and shutdown scripts, or system listeners. We recommend making complete backups of your Quartz, Hibernate, and Jackrabbit databases before continuing with the upgrade process.

  1. Stop your DI Server.
  2. Connect to the cmd line terminal for the DI Server. 
  3. At the prompt, run the DIServerConfigAndSolutionsBackup utility for your operating system.

    Windows

    DIServerConfigAndSolutionsBackup "C:\Program Files\pentaho\server\data-integration-server"
    

    Linux

    ./DIServerConfigAndSolutionsBackup.sh /opt/custom software/pentaho/server/data-integration-server
    

The next step is to install a new instance of Pentaho DI 6.0 software.

Step 2: Install Pentaho Data Integration 6.0 

A fresh archive installation of the Pentaho DI 6.0 package is needed as part of the upgrade process, after you have finished the upgrade prerequisites and backed up your Pentaho DI configuration and solutions files.  You'll need this in order to get all of the required updates.

Next, do these tasks from the Prepare Your Environment section of the archive installation guides. Make sure that you leave your Pentaho 5.x instance "as is" and unpack Pentaho 6.0 into a new directory. 

Windows

Linux

If you are using custom port numbers and a custom fully-qualified URL, there are some updates for 6.0 that you should be aware of. Changing Ports and URLs has information and steps for how to do both of these things for the DI Server in Pentaho 6.0.

Step 3: Restore Your DI Server Configuration and Solutions Files

After you have unpacked your Pentaho 6.0 bundle, restore your custom data to your 6.0 instance. 

If you do not wish to upload or replace your current sample data, it is recommended that you rename the files located in the pentaho-solutions/system/default-content directory prior to restarting the server. These files may include pentaho-operations-mart-etl, pentaho-operations-mart-operations, plugin-samples-zip, and samples-zip.

  1. Log in to your 6.0 DI Server and open a command prompt.
  2. In the prompt, run the DIServerConfigAndSolutionsRestore utility to restore your data from the .zip files in your user home folder. 

    Windows

    DIServerConfigAndSolutionsRestore "C:\Program Files\pentaho\server\data-integration-server"
    

    Linux

    ./DIServerConfigAndSolutionsRestore.sh /opt/custom software/pentaho/server/data-integration-server
    
  1. Restart the DI Server.

Step 4: Test Your New DI Server

The last thing that you will need to do before testing is to clear the cache from your web browser. 

Make sure that the DI Server and Spoon are running, then use this list to verify that your content has been restored to the DI Server.

  • Open old jobs and transformations and ensure that they execute properly.
  • Create a new job, transformation, and/or Agile BI analysis schema and save it as you normally would.
  • Schedule a job or transformation and ensure that the schedule executes properly.
  • Ensure that existing schedules are still valid.
  • If you are using an enterprise repository, share a job or transformation between PDI users and verify that both can access it.
  • Physically restart the server and ensure that the DI Server are automatically started as services.

Step 5: Update Your Pentaho DI Client Tool

The Pentaho DI client tool, Spoon, is easily updated on your workstations.

  1. Stop Spoon, if it is currently running.
  2. Move the old design tool out of the Pentaho folder structure to a temporary folder.
  3. Copy the new version of the design tool into the Pentaho folder structure.
  4. Restart your design tool.