Install Pega 7 on Tomcat and PostgreSQL

This post shows how to install the Pega 7 Exercise System on Tomcat 9 and PostgreSQL 9 – without the need for a virtual machine. Here, Mac OS X is used but the steps for Windows are essentially the same.

The Pega Exercise System, available at Pega Academy, provides a virtual machine disk (VMDK) file and requires a virtual machine player such as VMWare Workstation or Oracle VirtualBox to run. For details, see:

1. Download Pega 7 Application Files from Pega Exercise System Installation
2. Export Pega 7 Database from Pega Exercise System Installation
3. Install PostgreSQL 9 Database Server
4. Install the PostgreSQL PL/Java Extension
5. Import Pega 7 Database into PostgreSQL Server
6. Install Apache Tomcat 9
7. Configure Tomcat 9 and Install Pega 7 WAR Files

• Setup FTP Connection to Pega 7 Exercise System
• Access Pega 7 PostgreSQL DB with pgAdmin

• The Pega 7 application WAR file (prweb.war) can be obtained from a Pega Exercise System installation.
• Here, a Pega 7.1.9 Exercise System is installed and running on Oracle VM VirtualBox as explained in the Pega Academy Virtual Machine User Guide.

• The Pega 7.1.9 Exercise System provides an index page at <hostname>:9080 that shows system information. The super user credentials are used for FTP access.

• Any FTP client such as FileZilla can be used to download the Pega 7 application files.
• For detailed steps, see FTP Connection to Pega 7 Exercise System Running on a Virtual Machine.
• Connect to the Pega VM and navigate to the Tomcat webapps folder. For Pega 7.1.9, the location is:

/opt/tomcat/webapps

• Download the 3 WAR files of the Pega 7 Exercise System distribution:

• These WAR files will be used in section 7 and deployed to Tomcat 9 on the local machine.

• Use the VM command line interface to access the Pega 7 Exercise System.
• On Pega 7.1.9, the default credentials are username root and password install.
• Navigate to /usr/bin and execute the pg_dump program as shown below.

pg_dump -U pega pega > pega7db.pgsql

• The Pega 7 DB export may take a while and result in a fairly large file. Here it is 6.1 GB.

• Use the FileZilla FTP client again to download the Pega 7 DB file.

• Navigate to the PostgreSQL Download Site and click on the link for your OS.

• Select the PostgreSQL version and the OS from the drop downs. Here, PostgreSQL 9.6.5 is used.

• Run the downloaded installer file. Here the file is named postgresql-9.6.5-1-osx.dmg.
• Follow the installation instructions. The default settings are used in this example.

• The default Installation Directory is used: /Library/PostgreSQL/9.6

• The default Data Directory is used: /Library/PostgreSQL/9.6/data

• Enter a password and make sure to not lose it. Here, postgres is used.

• Make sure to keep the default PostgreSQL server port 5432.

• The installation should not take more than 5 minutes.

• After the PostgreSQL installation, download pgAdmin. Here, pgAdmin 4 v1.6 for Mac OS X was used.

• Start pgAdmin. It should automatically detect the running PostgreSQL server instance.

• On the left-hand side in pgAdmin, expand the Servers node, right-click on PostgreSQL 9.6, select Connect Server and enter the postgres password that was set during the installation.

• pgAdmin should now be connected to the local PostgreSQL server. The Databases node shows all databases. At this point, there will only be the default postgres DB.

• The Pega 7 database depends on the PostgreSQL PL/Java extension that allows procedures, triggers and functions to be implemented in Java. PL/Java must be built from source code using Maven.
• Pega 7 will not function without the PL/Java extension.
• Follow the steps in this section and if needed, refer to the PL/Java git hub site for details.

• The PL/Java source code can be dowloaded as a ZIP file from the PL/Java 1.5.0 release page or by cloning the GIT repository using the git command as shown below:

git clone https://github.com/tada/pljava.git -b REL1_5_STABLE

• After downloading and extracting the ZIP file or after cloning the git repository, the root folder of the PL/Java Maven project should look like below.

• Make sure that a Java JDK is installed. Here, Java JDK 8 is used.
• Download Apache Maven, install it and confirm that it is configured properly be executing:

mvn -version

• For additional details on installing Maven, see the Maven Quick Start guide.

• Maven must be able to execute pg_config located in <postgre-install-dir/bin>
• The PostgreSQL bin folder can be added to the PATH variable as follows:

export PATH=$PATH:/Library/PostgreSQL/9.6/bin

• Run pg_config to make sure it is accessible from the terminal. The expected output is shown below:

• Confirm that g++ is accessible from the terminal. The expected output is shown below:

g++ --version

• Navigate to the root folder of the PL/Java Maven project and trigger a build by executing:

mvn clean install

• During the build, there may be some warnings and errors related to Java types. These can be ignored.
• A successful build looks like the screen shot below. Refer to the PL/Java Build page for details or for information on debugging unsuccessful builds.

• See detailed PL/Java Installation instructions on the git hub site. For Mac OS X, from the PL/Java Maven project root folder, execute the JAR file that was created for your OS:

java -jar pljava-packaging/target/pljava-pg9.6-x86_64-MacOSX-gpp.jar

• Make sure to run the JAR file with a user that has sufficient privileges to write to the PostgreSQL installation folder. Running the JAR file creates a postgres/pljava folder in the PostgreSQL share folder and copies other PL/Java resources to the PostgreSQL installation.

• Open the PostgreSQL configuration file postgresql.conf. On Mac OS X, the default location is:

/Library/PostgreSQL/9.6/data/postgresql.conf

• At the bottom, under CUSTOMIZED OPTIONS, add below lines to configure the PL/Java extension.

#------------------------------------------------------------------------------
# CUSTOMIZED OPTIONS
#------------------------------------------------------------------------------

# Add settings for extensions here
pljava.libjvm_location = 
'/Library/Java/JavaVirtualMachines/jdk1.8.0_77.jdk/Contents/Home/jre/lib/jli/libjli.dylib'
pljava.classpath = '/Library/PostgreSQL/9.6/share/postgresql/pljava/pljava-1.5.1-SNAPSHOT.jar'
pljava.statement_cache_size = 10
pljava.release_lingering_savepoints = true
pljava.vmoptions = '-Xms32M -Xmx64M -XX:ParallelGCThreads=2'
pljava.debug = false

• Restart the PostgreSQL server and open pgAdmin to continue.

• In pgAdmin, create the Pega 7 DB user named pega by executing the SQL command below.

CREATE USER pega WITH
  LOGIN
  SUPERUSER
  INHERIT
  NOCREATEDB
  NOCREATEROLE
  NOREPLICATION;

• In pgAdmin, create the Pega 7 database named pega using the SQL command below.

CREATE DATABASE pega
    WITH 
    OWNER = pega
    ENCODING = 'UTF8'
    TABLESPACE = pg_default
    CONNECTION LIMIT = -1;

• Execute the SQL commands below to configure the pega user and to set the password to pega.

ALTER ROLE pega IN DATABASE pega SET search_path TO pegadata, pegarules, public;
ALTER USER pega WITH PASSWORD 'pega';

• Right-click on the pega database node and select the Query Tool.
• Execute the below SQL command to add the extension for PL/Java to the pega database.

CREATE EXTENSION pljava;

• To test the extension, run the below SQL command to define a new Java-based function:

CREATE FUNCTION getsysprop(VARCHAR)
RETURNS VARCHAR
    AS 'java.lang.System.getProperty'
LANGUAGE java;

• Then, run the function using the syntax below:

SELECT getsysprop('java.version');

• It should return the Java version that PL/Java is using.

• The PL/Java extension for PostgreSQL is now installed for the pega database.

• Import the file pega7db.pgsql into the local PostgreSQL instance using the psql tool.

/Library/PostgreSQL/9.6/bin/psql -U pega pega < pega7db.pgsql

• The Pega 7 database will be completely recreated by the import.
• pgAdmin can be used to compare the imported DB to the one on the exercise system.

• Navigate to the download section on the Apache Tomcat home page and select the link for your OS.
• Here, Mac OS X is used as the target system and the binary distribution apache-tomcat-9.0.0.M26.tar.gz is used.

• Uncompress the downloaded file to some folder. Here, Tomcat 9 is installed at apache-tomcat-9-A.

• Open a new Terminal and navigate to the Tomcat 9 bin folder. Run startup.sh to start Tomcat.

• In a browser, access http://localhost:8080 to confirm that the Tomcat 9 server is running.

• By default, the Tomcat 9 context.xml file, located in <tomcat-root>/conf, contains:

<?xml version="1.0" encoding="UTF-8"?>
<!--
  Licensed to the Apache Software Foundation (ASF) under one or more
  contributor license agreements.  See the NOTICE file distributed with
  this work for additional information regarding copyright ownership.
  The ASF licenses this file to You under the Apache License, Version 2.0
  (the "License"); you may not use this file except in compliance with
  the License.  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
-->
<!-- The contents of this file will be loaded for each web application -->
<Context>

    <!-- Default set of monitored resources. If one of these changes, the    -->
    <!-- web application will be reloaded.                                   -->
    <WatchedResource>WEB-INF/web.xml</WatchedResource>
    <WatchedResource>WEB-INF/tomcat-web.xml</WatchedResource>
    <WatchedResource>/conf/web.xml</WatchedResource>

    <!-- Uncomment this to disable session persistence across Tomcat restarts -->
    <!-- <Manager pathname="" />   -->
</Context>

• Modify the context.xml file as shown below to add the Pega 7 DB JDBC connection parameters.

<?xml version='1.0' encoding='utf-8'?>
<!--
  Licensed to the Apache Software Foundation (ASF) under one or more
  contributor license agreements.  See the NOTICE file distributed with
  this work for additional information regarding copyright ownership.
  The ASF licenses this file to You under the Apache License, Version 2.0
  (the "License"); you may not use this file except in compliance with
  the License.  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
-->
<!-- The contents of this file will be loaded for each web application -->
<Context>

<Resource name="jdbc/PegaRULES" auth="Container" type="javax.sql.DataSource" 
    driverClassName="org.postgresql.Driver" url="jdbc:postgresql://127.0.0.1:5432/pega" 
    username="pega" password="pega" initialSize="11" maxActive="100" maxIdle="30" maxWait="10000"/>

<Environment name="prconfig/database/databases/PegaRULES/defaultSchema" 
    value="pegarules" type="java.lang.String" />
<Environment name="prconfig/database/databases/PegaDATA/defaultSchema" 
    value="pegadata" type="java.lang.String" />
<Environment name="url/initialization/explicittempdir" value="path" type="java.lang.String"/>

    <!-- Default set of monitored resources -->
    <WatchedResource>WEB-INF/web.xml</WatchedResource>

    <!-- Uncomment this to disable session persistence across Tomcat restarts -->
    <Manager pathname="" />

    <!-- Uncomment this to enable Comet connection tacking (provides events
         on session expiration as well as webapp lifecycle) -->
    <!-- <Valve className="org.apache.catalina.valves.CometConnectionManagerValve" /> -->
</Context>

• Download the PostgreSQL JDBC driver from https://jdbc.postgresql.org/download.html.
• For Java 8, use version 4.2. Copy the JAR file into <tomcat-root>/lib.
• Copy the 3 WAR files listed in section 1 into the <tomcat-root>/webapps folder.

• Tomcat will automatically deploy the WAR files and start the Pega 7 application.
• The Pega 7 Designer Studio can now be accessed at:

http://localhost:8080/prweb/PRServlet

• The Pega 7 Online Help can now be accessed at:

http://localhost:8080/prhelp/procomhelpmain.htm#home.htm

• The Pega 7 System Management Application can now be accessed at:

http://localhost:8080/prsysmgmt/index.jsp