Docker – Part 4 – Run Pega as a docker container

This is the final blog article on Docker series, where we will see how we can run a Pega docker container.

I strongly recommend you go through all the 3 previous articles on Docker for better understanding. If you are a docker expert, then no need 😉

https://myknowtech.com/tag/docker

All the commands in this post can be found the git repository –

https://github.com/Prem1991/myknowpega/tree/master/docker

Now think, what are the minimum software needed to run a Pega application?

Two things will come into mind

A webserver ( or an app server) like Tomcat to run the web application

A database server like Postgres holds the entire rule base and other data.

Putting this in container terms, to run your Pega application in a docker container, you need to run two containers – a web server – a tomcat container and a database server – a Postgres container.

As soon as containerization became trending, every tech giant started their investment to make their applications container-ready (mostly docker-ready). Years before Pega also started their research and published multiple images for different Pega flavors.

You can visit official Pegasystems images in dockerhub.

You see they joined in 2016 and they have 8 repositories as of now and they do update the main repositories frequently with new changes 🙂

Note: Some of the images are fully baked those you can use as such and some are half baked which you can use as a base image and build your changes over.

So to run your Pega docker container, you can either build your image from scratch or use these official pega images. I am going to stick with the Pega principles – Always reuse 😉 Build for change 🙂

I am choosing two images

1. pegasystems/postgres-pljava-openjdk – for running postgres
2. pegasystems/pega-ready  – for running web application in tomcat server.

Two main parts in this tutorial, first we will start with setting up a Postgres container and load it with our pega rule engine (necessary schemas) and then we will set up a tomcat server, connect to the Postgres and launch our Pega web application.

How to start a Pega postgres container?

Step 1: Explore the right base image and tag.

As I mentioned before, we will use the pegasystems/postgres-pljava-openjdk as our base image.

What is pljava?

PL/Java is an add-on module to Postgres that brings the Java stored procedures, triggers, and functions into Postgres database.

Do we use Java functions in the pega database? – Yes, remember the pr_read_from_stream function which is used to read the blob data from the database. These are Java functions. So with Postgres without pljava, you cannot use these functions.

Now think, if you need to install pega on postgres (without containers), you need to manually install it from the media file in the resource kit.

You can find it under the installation guide – https://community.pega.com/knowledgebase/documents/pega-platform-85-installation-guide-apache-tomcat-and-postgresql

Similarly to run a pega postgres container, we somehow need to install it!, Pega provided image already supports this, we don’t need to do any additional work to install it.

Note: If you choose postgres official image as the base image, then you need to add these jars in your Dockerfile.

You can read more about our base image – https://hub.docker.com/r/pegasystems/postgres-pljava-openjdk

If you click on the Tags, tab, there you have 3 tags (flavours) of docker image – 9.4, 9.6 and 11.

I am going to use the highest version Postgres 11.

It will be interesting to check the base Dockerfile right?!!.

You can check it from Pega official git repository

https://github.com/pegasystems/postgres-pljava-openjdk

First let’s look at the docker file.

You will see the base image is from official postgres:11. You will also see other package manager run instructions.

Why there is another folder – docker-entrypoint-initdb.d?

You know what is entrypoint in docker terms – we saw in the previous post. It can be like the first command to be executed on running the container.

If you look the official Postgres dockerfile, you will see, that it executes all the files that stay under this folder.

So whoever building multiple layers over the Postgres image, if they want to execute any other SQL commands or any, just use an ADD instruction to add your SQL files into the directory.

Above you see an SQL file, that will help to install pljava.

We browsed enough of the base image.

Step 2: Build your own docker file for postgres container.

In a real-time development environment with CICD in place, usually, you will be having repositories or any of the source version control like – git or with azure DevOps repositories.

For now, I will have separate directories in my local machine.

Step 2.1: Create a new directory

dockerrepos and create a subdirectory – postgres

Step 2.2: Set up your IDE.

You can use any IDE to start creating Dockerfile.

You can always use Notepad to create Dockerfile, But I would suggest you to use some IDE. I prefer VS code.

The advantage is, you can install the right plugins/extensions, that can help with validation and autocomplete for docker instructions.

In the extension Marketplace, I installed docker extension.

Now you can open your folder from your local machine, or if you use repository you can clone from it.

You can always add files and folders from the explorer.

Step 2.3: Create a new docker file.

You can also find the entire dockerfile content in the git repository – https://github.com/Prem1991/myknowpega/tree/master/docker/postgres

Important note: The file should always be in the same naming format – Dockerfile. You see a beautiful whale icon in the left. IDE recognizes your file.

Add the default first instruction – FROM

You see the power of IDE, it tries to auto completes you with list of base images.

Now what customization do we need to do with the official base image?

For now not much just we need to add a data folder.

By default, postgres defined a volume mount – /var/lib/postgresql/data

Below is the snippet from official postgres image.

But in google, few people mentioned they faced some permission issue using this volume directory to mount. To counter that, we can create a new data folder and set the location to PGDATA environment variable

You can read about PGDATA in the following link – https://hub.docker.com/_/postgres

RUN mkdir -p /var/lib/postgresql-persist/data

ENV PGDATA var/lib/postgresql-persist/data

So that is how my custom Dockerfile is looking.

Now it is time to build our own custom image – pegapostgresdocker.

Step 2.4: Build the custom pega postgres docker image.

Open the terminal and switch to postgres directory.

This is a new command – docker build <option> <imagename> <dockerfile location>

I am going to use option –t to specify the tag for my image

For other options for docker build command – https://docs.docker.com/engine/reference/commandline/build/

docker build –t pegapostgres:11 .

Note: Don’t forget the . (dot) at the end, that helps the build command to identify the Dockerfile location

You should see the image layers getting build

At the end you will the pegapostgres image in the dockerdesktop

You can also use the command docker images to list down the available local images.

Step 3: Run the Postgres container.

Now our image is ready, we can start running the Postgres container.

In the last article, we saw running the docker container using port mapping as well as volume mount. We will do the same here.

Step 3.1: Create a new volume mount.

Docker volume create pegaapp

You can also check the created volume using – docker volume ls

Step 3.2: Run the Postgres container with the right options.

Below is my command

docker run –name pegapostgres -p 5432:5432 -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=postgres -v pegaapp:/var/lib/postgresql-persist/data pegapostgres:11

name = container name

-p = port mapping between container and docker host

-e = environment variables for username and password.

-v = volume mount

And finally the image name with tag.

In the logs, you will see the pljava installation everything.

Container is up and running now 🙂

Till now we ran a Postgres container, now we should specialize it for pega right??

I mean to install the pega schemas and rule engine.

Step 4: Make the running Postgres container –  Pega ready.

How do we normally install pega on Postgres? Ideally, with a full license, you will get the media file with the install.sh scripts, providing you with some connection properties.

But here I am not going to use the original media file, instead, I need to live with the personal edition media file.

Think how Pega personal edition works?

– You get a zip from the pega community site.

– You unzip it and run the installation bat file.

– It may take around 30 odd minutes to load the rulebase.

The trick is, on the extracted zip, you will find the dump file to get restored in the postgres database.

Pega.dump file is the main one. If you see the installation log file, pg_restore uses this dump file and loads the postgres database

Now we know how to install the rulebase in running postgres from pega.dump file

Step 4.1: Copy the pega.dump file into postgres location.

First move the dump file into our present working directory.

Now move the file into the running container’s known location.

docker cp <dump file location> <containername:container file location>

docker cp pega.dump pegapostgres:/var/lib/postgresql-persist/data

It will take a couple of minutes (it may look as if nothing is happening without logs, so don’t worry. Wait for it )

Done

To verify, you can use docker exec command to open up a bash terminal, and then you are into the container.  You can check the content of the file structure inside the container.

With docker desktop, you can easily use an CLI in the running environment.

The file is inside.

Step 4.2: Inside the container, you can execute the pg_restore command

pg_restore –U <username> -d <databasename> <dump file location>

pg_restore -U postgres -d postgres pega.dump

It will take more than 30 minutes to load the database. Again, you will not see any logs, don’t worry about it! Take a short break ( your system can also hang a little)

Okay, the command was completed without any error.

We completed half of the tutorial :). Next half.

How to start the Pega web app container?

Step 1: Explore the right base image.

As I told in the start, we will use the Pega official image –

Pegasystems/pega-ready

https://hub.docker.com/r/pegasystems/pega-ready

I will use the latest tag.

If you read the description, it clearly says, the image cannot be run without modification. You need to add the web application archive.

You can check their git repository for the Dockerfile specification – https://github.com/pegasystems/docker-pega-web-ready

You will see it is built using another Pegasystems base image –

Just go through the docker file on your own and try to relate why they are using different instructions.

Please read the readme content. My Pega custom image is influenced by the content in the readme file.

Step 2: Create a new directory for pegaweb

Step 3: Create a new Docker file

You can also find the entire dockerfile content in the git repository – https://github.com/Prem1991/myknowpega/tree/master/docker/pegawebapp

Step 3.1: Use the base image – pegasystems/pega-ready

Step 3.2: Extract and copy the prweb archive.

Locate the prweb file from your personal edition location. C:PRPCPersonalEditiontomcatwebapps

Use any file extractor tool to extract the content into our pegaweb directory.

You will see the entire content extracted.

If you want to update any of the configuration files like prconfig.xml or prlog4j2.xml, you can always do that.

In the docker file, I am going to copy the extracted prweb content into the containers webapps/prweb folder.

COPY <permission> <source location> <target location>

COPY –chown=pegauser:root /prweb ${CATALINA_HOME}/webapps/prweb

RUN chmod -R g+rw   ${CATALINA_HOME}/webapps/prweb

Whatever files you add, make sure you provide permission to the system user.

I see pegauser is mentioned in the base dockerfile to execute the scripts, so giving the permission to the user. Also CATALINA_HOME env variable is set in the underlying image.

Step 3.3: Add the right jdbc driver.

You need to add the jdbc driver in the catalina home lib folder.

Choose the right JDBC driver. I am using 42.2.20

https://jdbc.postgresql.org/download.html

 Copy the downloaded jar into the pegaweb directory.

Now add the final instruction in the docker file to copy the postgres jar into container filesystem at runtime.

COPY –chown=pegauser:root postgresql-42.2.20.jar ${CATALINA_HOME}/lib/

Save the file. Now my file is ready 🙂

Step 4: Build the custom pega webapp image.

Open the terminal and switch to pegaweb directory

Use the build command to build the new image.

Since I used the prweb.war from my 8.5.1 personal edition, I will use the tag 851

docker build –t pegawebapp:851 .

layer building

Once completed, you should see the image on the docker desktop.

Now the final step.

Step 5: Run the pega container

docker run –name pegawebapp -p 8080:8080 -e JDBC_URL=jdbc:postgresql://pegapostgres:5432/postgres –link pegapostgres:pegapostgres -e JDBC_CLASS=org.postgresql.Driver -e DB_USERNAME=postgres -e DB_PASSWORD=postgres pegawebapp:851

Name = specifies the name of the container.

-p = port mapping between container and docker host.

–link is basically to make a bridge between containers

Important note: link is a legacy and can be removed.

4 environment variables

JDBC_URL  = jdbc:postgresql://<linked postgrescontainername>:<portnumber>/postgres

JDBC class = for postgres, org.postgresql.Driver

DB_USERNAME and DB_PASSWORD

Finally the image name with tag 851

You can also run different pega containers, using different port and name

Happiness is seeing your Pega running inside a container 😀

In the system information, you will see the container ID as well as openJDK with postgres 11 specifications

I also verified the Postgres persistent part. So once you remove the Postgres container and then start it again, none of your data will be lost. unless you uninstall your docker desktop, since we did volume mount on docker host, it basically sits under the application data folder.

So far what you see is very basic about running pega containers. In real-time you will have a lot of instructions in your Dockerfile. I feel this serves as a base and you can learn and master docker from here. You may also use Docker compose to run your Pega containers.

Try to customize the prconfig, prlogging, try node classification or add locale and timezone settings in your docker containers.

Hope you guys liked the docker series.