Pentaho upgrade
This guide describes how to upgrade the Pentaho Server from the archive installation of Pentaho version 7.x or 8.x to Pentaho 8.3. This upgrade documentation assumes that you are upgrading to 8.3 on the same server as your current archive installation.
If you are currently using Pentaho 7.x or 8.x that was previously upgraded to the DI Server only, use the Upgrade from 7.x or 8.x DI Server to 8.3 upgrade instructions.
Get started with the 8.3 upgrade
To perform this upgrade process, you need to know how to access the Pentaho Server as an Administrator from a command line.
Before you begin
Procedure
Verify your current version of the Pentaho Suite. Start with a working installation of Pentaho Server 7.x or 8.x.
Verify that your system components are current. Ensure that your system components, such as web browsers or repository databases, are up-to-date for Pentaho.
Create backups of all the following Pentaho databases:
- hibernate
- quartz
- jackrabbit
For Linux installations only, verify Info-ZIP has been installed and configured.
If needed, you can download, install, and configure Info-ZIP open source compression utility using the Info-ZIP documentation. Info-ZIP is available at http://www.info‐zip.org/. A BSD-style license is provided and used for most Linux and Unix variants. A Windows version of Info-ZIP is pre-configured and included in the Pentaho update package.Verify that no users are logged on to the server.
The upgrade process should be performed during off-business hours to minimize impact to your day-to-day operations.
Next steps
Get the Pentaho upgrade and utility files
The upgrade process involves utility and installation files that you must download from the Pentaho Customer Support Portal.
Download the upgrade and utility files
Procedure
On the Customer Portal home page, sign in using the Pentaho support user name and password provided in your Pentaho Welcome Packet.
Click Downloads, then click Pentaho 8.3 GA Release in the 8.x list.
On the bottom of the Pentaho 8.3 GA Release page, browse the folders in the Box widget to find the files you need, including the pentaho-upgrade-utility-8.3.x.yy-pentaho file in the Utilities and Tools folder.
Available update files
Component | File Name |
Pentaho Server Upgrade Utility | pentaho-upgrade-utility-8.3.x.yy-pentaho |
Pentaho Server Installation | pentaho-server-ee-8.3.x.yy-dist |
PDI client | pdi-ee-client-8.3.x.yy-dist |
Pentaho Analyzer | paz-plugin-ee-8.3.x.yy-dist |
Pentaho Dashboard Designer | pdd-plugin-ee-8.3.x.yy-dist |
Pentaho Interactive Reports | pir-plugin-ee-8.3.x.yy-dist |
Report Designer | prd-ee-8.3.x.yy-dist |
Metadata Editor | pme-ee-8.3.x.yy-dist |
Schema Workbench | psw-ee-8.3.x.yy-dist |
Aggregation Designer | pad-ee-8.3.x.yy-dist |
License Files | Pentaho [component] Enterprise Edition.lic |
Unzip the downloaded files
Procedure
If needed, move the downloaded files to a temporary location on your current server.
Unzip each downloaded file.
Next steps
Upgrade the Pentaho Server
The following steps will guide you through the version 8.3 Pentaho Server upgrade process:
- Back up your Pentaho Server configuration and solutions files
- Install the version 8.3 Pentaho Server and plugins
- Restore your server configuration and solutions files
- Consider previous version upgrades and customizations
- Start and test the Pentaho Server
This process assumes you have completed an archive installation of the version 7.x or 8.x Pentaho Server and are upgrading to version 8.3.
Step 1: Back up your Pentaho Server configuration and solutions files
Complete the following steps to back up your configuration and solutions files:
Procedure
Stop the Pentaho Server.
Open a command line terminal and navigate to the unzipped directory of the pentaho-upgrade-utility-8.3.x.yy-pentaho upgrade utility.
At the prompt, run the correct PentahoServerConfigAndSolutionsBackup utility for your operating system as shown below:
- Windows:
PentahoServerConfigAndSolutionsBackup.bat <path to your 7.x or 8.x pentaho server>
NoteIf you are using Windows and the directory path you specified contains white spaces, then be sure to wrap it in double quotation marks (“). - Linux:
./PentahoServerConfigAndSolutionsBackup.sh <path to your 7.x or 8.x pentaho server>
The backup utility has the following optional parameters:
pentaho_solutions_folder
Specifies the path to the pentaho-solutions directory if you manually installed it outside of the main pentaho directory structure.
pentaho_version
Specifies your Pentaho Server version if a valid version cannot be automatically found during the backup process.
- Windows:
Next steps
Step 2: Install the 8.3 Pentaho Server and plugins
After completing Step 1, you are ready to install the 8.3 Pentaho Server and related plugins.
Make sure to install the new instance of Pentaho on the same server, but leave your Pentaho 7.x or 8.x instance "as is" while unpacking Pentaho 8.3 into a new directory.
Pentaho Server installation
Procedure
Verify Java 8 is installed on the server machine.
If you need to install Java 8, you can download a supported version of JRE or JDK.Verify the PENTAHO_JAVA_HOME environment variable is set to the path of your Java installation.
- If you need to set this variable, use the SET command in Windows or the export command in Linux.
- If you are using a JRE, verify the JRE_HOME environment variable is also set to the correct location.
Browse to the location where you unzipped the pentaho-server-ee-8.3.x.yy-dist file in the Available Update Files section.
Execute the supplied install.bat or install.sh file.
Agree to the end-user license agreement.
Select the pentaho/server/pentaho-server directory as the location to store the extracted files.
Plugin installation
- paz-plugin-ee-8.3.x.yy-dist
- pir-plugin-ee-8.3.x.yy-dist
- pdd-plugin-ee-8.3.x.yy-dist
If you use any of these plugins, browse to the location where you unzipped these distributions and perform the following steps for each file:
Procedure
Execute the supplied install.bat or install.sh file.
Agree to the end-user license agreement.
Select the pentaho/server/pentaho-server/pentaho-solutions/system directory as the location to store the extracted files.
Step 3: Restore your server configuration and solutions files
Perform the following steps to apply the PentahoServerConfigAndSolutionsRestore utility:
Procedure
Delete the content in the version 8.3 Pentaho Server pentaho-solutions/system/default-content directory.
Open a command line terminal and navigate to the unzipped directory of the pentaho-upgrade-utility-8.3.x.yy-pentaho.
In the prompt, run the PentahoServerConfigAndSolutionsRestore utility to restore your data from the ZIP files located in your user home directory as shown below:
- Windows:
PentahoServerConfigAndSolutionsRestore.bat <path to 8.3 pentaho server>
NoteIf you are using Windows and the directory path you specified contains white spaces, then be sure to wrap it in double quotation marks (“). - Linux:
./PentahoServerConfigAndSolutionsRestore.sh <path to 8.3 pentaho server>
- Windows:
Step 4: Review previous version upgrades and customizations
This section includes version specific and configuration changes that should be reviewed.
Verify spring security namespace header updates
Perform the following steps to verify the spring-security namespace headers:
Procedure
Stop the Pentaho Server.
Open the following three files:
/pentaho-server/pentaho-solutions/system/applicationContext-spring-security.xml
/pentaho-server/pentaho-solutions/system/applicationContext-spring-security-cas.xml
/pentaho-server/pentaho-solutions/system/repository.spring.xml
Locate the spring-security namespace in each file header. If it is not already updated, enter the following version:
http://www.springframework.org/schema/security/spring-security-4.2.xsd
Save and close the files.
Results
Karaf customizations
The Pentaho Server installs all the Karaf features upon installation. The system waits for these features to be installed before timing out. The default is to wait two minutes before timing out. If you modified any Karaf feature, you should consider changing the Karaf startup timeout setting.
Password encoding
- You are upgrading from version 8.1 to 8.3.
- You are using your own password encoding or you previously applied this version of encoding
If you wish to use this version of password encoding, perform the following steps:
Procedure
Navigate to the pentaho/server/pentaho-server/pentaho-solutions/system directory and open the pentahoObjects.spring.xml file with any text editor.
Locate the line that contains
bean id="IPasswordService"
.Verify or modify the
class=<value>
with the following value:bean id="IPasswordService" class="org.pentaho.platform.util.KettlePasswordService" scope="singleton"/>
Save and close the file.
If you modified the
class=<value>
above, you must make the following modification to encrypt the Pentaho Admin password. In the same pentaho/server/pentaho-server/pentaho-solutions/system directory, open the defaultUser.spring.properties file with any text editor.Locate the following lines:
defaultAdminUserPassword=cGFzc3dvcmQ=
defaultNonAdminUserPassword=cGFzc3dvcmQ=
Replace the values in these lines with the following values:
defaultAdminUserPassword=Encrypted 2be98afc86aa7f2e4bb18bd63c99dbdde
defaultNonAdminUserPassword=Encrypted 2be98afc86aa7f2e4bb18bd63c99dbdde
Save and close the file.
Documentation version link
Procedure
Navigate to the pentaho/server/pentaho-server/pentaho-solutions/system directory and open the pentaho.xml file with any text editor.
Modify the following
<documentation-url>
line and replace the previous documentation value with the current documentation value:<documentation-url>https://help.pentaho.com/Documentation/8.3/Products/User_Console</documentation-url>
Save and close the file.
CORS (for embedding CTools)
Procedure
Navigate to the pentaho/server/pentaho-server/pentaho-solutions/system directory and open the pentaho.xml file with any text editor.
Modify or add the following
CORS
lines:<!-- cors-requests-allowed: Flag indicating if cross-origin requests are allowed or not. accepted values are: true | false --> <cors-requests-allowed>false</cors-requests-allowed> <!-- cors-requests-allowed-domains: Comma separated list of domains allowed to do cross-origin requests to the server. Example: http://domainA.com, http://localhost:1337 --> <cors-requests-allowed-domains><!-- allowed domains here --></cors-requests-allowed-domains>
If you are embedding CTools, add the following line (as shown above) and set the value to true.
<cors-requests-allowed>true</cors-requests-allowed>
Save and close the file.
Previously customized files
If you have previously customized any of the following items, verify that your customizations have been carried forward:
- server.xml
- startup and shutdown scripts
- system listeners
- security configuration files
If your previous customizations have not been merged, incorporate them into their 8.3 files.
Step 5: Start and test the Pentaho Server
You are now ready to Start your 8.3 Pentaho Server.
Test your server
Procedure
Clear your web browser cache and history.
Navigate to your Pentaho URL (the default URL is
http://localhost:8080/pentaho
) and ensure the login screen appears.Log on to PUC and try to run your existing content.
Verify your schedules exist and are working properly.
Ensure your Pentaho plugins are installed and functional by performing the following tasks:
- Open a report that requires no user prompts or parameters.
- Create a test report for Interactive Reports and a test report for Analyzer.
- Open a dashboard in Dashboard Designer.
Examine the application server logs for any errors:
- Check your Catalina and Pentaho logs in the server/pentaho-server/tomcat/logs directory.
Log on and try to access the kettle/status page.
Next steps
Update your design tools
Procedure
Exit any of the design tools, if any are currently running.
Back up and rename all the 7.x or 8.x existing directories in a separate, temporary directory.
Browse to the location where you downloaded the following -dist files in the Available Update Files section:
- pdi-ee-client-8.3.x.yy-dist
- prd-ee-8.3.x.yy-dist
- pme-ee-8.3.x.yy-dist
- psw-ee-8.3.x.yy-dist
- pad-ee-8.3.x.yy-dist
If you have not already done so, unzip all the new design tools directories and install them into a pentaho/design-tools directory.
Start your new design tools to verify they were upgraded to 8.3.
Test the functionality of the design tools.
Results
For customers using Analyzer
Analyzer can be upgraded from Visualization API 2.0 to Visualization API 3.0. Before upgrading, please review the following information for more details: Analyzer and the Visualization API.
For customers using Ops Mart
If you installed an Ops Mart as part of the previous Pentaho 7.x or 8.x upgrade, you do not have to reinstall it.
If you are interested in installing and using DI Ops Mart, see Install DI Ops Mart.