Prepare your hosts for migration.
After you have prepared your migration plan, prepare your environment.
Install 5.x.x BA Server and Licenses
Complete these steps to install the 5.x.x BA Server and licenses.
If you are going to install the 5.x.x BA Server on the same machine as the 4.8.x one, consider keeping the 4.8.x version of BA Server running as you install the 5.x.x BA server to avoid port conflicts. When you use the Wizard to install the 5.x.x BA Server, it senses what ports are being used at the time of installation and, if the port is used, it assigns a different port for the newly installed BA Server. If the 5.x.x and 4.8.x BA Servers run on different ports, they can both run at the same time. This is helpful during the Verify BA Migration step, which occurs later in these instructions, because you will need to run both systems at the same time to verify that content has migrated from the 4.8.x system to the 5.x.x one.
- Install the 5.x.x version of the BA Server. See Select BA Installation Options to determine the best installation option. Make sure that you install the samples as well.
- Install the license keys and modify the startup scripts as needed. To avoid problems with the Migration Tool and to avoid any of your changes being overwritten, the 5.x.x server should be in a "pristine" state; do not configure the system further, just modify the startup scripts and install the license keys.
- Make sure that you have an environment variable set for $PENTAHO_INSTALLED_LICENSE_PATH. The variable should be set to the path where the licenses are installed. (This is usually your home directory or the directory where Pentaho was installed.)
- To verify that the BA Server was installed properly, start the BA Server and log in as the admin user. Make sure to clear your browser's cache if necessary, but do not make any additional changes. If you have any problems starting the BA Server, fix the problem before proceeding further.
Download and Install the Migration Tool
The Migration Tool automates the data migration process. The Export Data and Import Data sections provide details on how to use the Migration Tool to perform the migration process.
The installation program for the Migration Tool requires the currently supported version of Oracle Java. We recommend that you download and install the Migration Tool on the same computer where the 5.x.x version of the server is installed because Java will have already been installed on that computer during the installation process.
- Download the pentaho-platform-migrator-5.x.x-dist.zip file from the Customer Support Portal on the computer where the 5.x.x version of the server has been installed.
- Unzip the file using the unzip program of your choice. It does not matter where you unzip it.
- If you use Windows, open the Command Prompt window. If you use Linux, open the Terminal window.
- Install the Migration Tool by doing one of the following.
- If you use Windows, enter this command: install.bat
- If you use Linux, enter this command: ./install.sh
- Read the EULA that appears. Select I accept the terms of this license agreement, then click Next.
- Indicate where you want the file to be unpacked. It doesn't matter where you download the file. Click the Next button.
- The Installation Progress window appears. Progress bars indicate the status of the process. When the process is complete, click Quit to exit.
- If the 4.8.x version of the BA Server is on another computer, you need to install a copy of the Migration Tool there. The 4.8.x version of the BA Server runs on Java 1.6. You can run the Migration Tool on Java 1.6, but the installation program for the Migration Tool requires Java 1.7. So, to address that issue, we recommend that you copy the Migration Tool directories and files that you already unpacked and installed on the 5.x.x system to the 4.8.x one.
Increase Memory Allocated to the 4.8.x Server
The Migration Tool requires 2 gigabytes of RAM to run. Since the Migration Tool launches a mini-version of the server, the Migration Tool uses the same memory that you have allocated for the server. Since the 4.8.x version of the BA Server had less memory allocated by default, you will need to check the memory settings for the server, then make adjustments if necessary.
- Review the instructions in the Changing the Java VM Memory Limits that is in version 5.x of Infocenter for your operating system and installation type. Then do these things.
- Complete the steps for stopping the server.
- Ensure that the memory settings for the minimum and maximum Java heap size parameters (-Xms and -Xmx) are both set to at least 2048m or higher. If the parameters are greater than 2048, leave as is, only make changes if the setting is less than 2048.
- Windows Example:
export CATALINA_OPTS="-Xms2048m -Xmx2048m -XX:MaxPermSize=256m -Dsun.rmi.dgc.client.gcInterval=3600000 -Dsun.rmi.dgc.server.gcInterval=3600000"
- Linux Example:
export JAVA OPTS="-Dpentaho.installed.licenses.file=/opt/pentaho/.installedLicenses.xml -Xms2048m Xmx2048m -XX-MaxPermSize=256m -Dsun.rmi.dyc.client.gcInterval=3600000 -Dsun.rmi.dgc.server.gcInterval=3600000"
- Restart the 4.8.x version of the server and verify that it starts correctly.