From b551164a4618c241b394c67202b4556dc9dbd9a2 Mon Sep 17 00:00:00 2001 From: Kinga Kowalska <120555574+kingakowalska1@users.noreply.github.com> Date: Tue, 20 Aug 2024 12:05:53 +0200 Subject: [PATCH 1/2] BUG-883938 Move Build custom pega-web-ready doc to the main readme --- README.md | 29 +++++++++++++++++++++++++---- 1 file changed, 25 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 6123f4bc..61dede5b 100644 --- a/README.md +++ b/README.md @@ -1,19 +1,40 @@ Pega Docker Image =========== -Pega Platform is a distributed web application for customer engagement, customer service, and digital process automation. A Pega deployment consists of a number of containers connecting to a Database and any other required backing services. The Pega database contains business rule logic that must be preloaded with an installer for the containers to successfully start. For more information and instructions on how to get started with a container based deployment of Pega, see [Pega's Cloud Choice documentation](https://community.pega.com/knowledgebase/articles/cloud-choice). +Pega Platform is a distributed web application for customer engagement, customer service, and digital process automation. A Pega deployment consists of a number of containers connecting to a Database and any other required backing services. The Pega database contains business rule logic that must be preloaded with an installer for the containers to successfully start. For more information and instructions on how to get started with a container based deployment of Pega, see [Pega's Cloud Choice documentation](https://docs.pega.com/bundle/platform/page/platform/deployment/client-managed-cloud/containerized-deployments-kubernetes.html). [![Docker Image Build](https://github.com/pegasystems/docker-pega-web-ready/actions/workflows/docker-build.yml/badge.svg?branch=master)](https://github.com/pegasystems/docker-pega-web-ready/actions/workflows/docker-build.yml) [![Docker Image](https://img.shields.io/docker/pulls/pegasystems/pega)][pegasystems/pega] # Using this image -This *ready* Docker image extends a customized Tomcat base image `pegasystems/tomcat:9-jdk11` and contains required components that allow you to run a Pega Platform on your deployment nodes. It does not include Pega Platform rules. This image is web-ready for clients to build a final image that includes the Pega .war file of your choice. +The [pegasystems/pega-ready](https://hub.docker.com/r/pegasystems/pega-ready) Docker image extends a customized Tomcat base image with either JDK11 or JDK17 and contains required components that allow you to run a Pega Platform on your deployment nodes. It does not include Pega Platform rules. This image is web-ready for clients to build a final image that includes the Pega .war file of your choice. -Pega offers an alterative, full image which *includes* the .war file - for details, see [pegasystems/pega on DockerHub][pegasystems/pega]. Docker images provided by Pegasystems are validated and supported by [Pega Support](https://community.pega.com/support). +Pega offers an alterative, full image which *includes* the .war file - for details, see [pegasystems/pega on DockerHub][pegasystems/pega] and [Pega-provided Docker images](https://docs.pega.com/bundle/platform/page/platform/deployment/client-managed-cloud/pega-docker-images-manage.html). Docker images provided by Pegasystems are validated and supported by [Pega Support](https://community.pega.com/support). ## Image customizations -If you do not want to use the Pega-provided Docker image, you can copy this repository and build your own image based on your preferred base image such as one enforced by a corporate standard. When making customizations for your environment, check the [Pega Platform Support Guide Resources](https://community.pega.com/knowledgebase/articles/pega-platform-support-guide-resources) to verify that those changes are supported by your Pega Platform version. If you choose to build your own image, Pega will continue to offer support for Pega Platform, but problems that arise from your custom image are not the responsibility of Pegasystems. +If you do not want to use the Pega-provided Docker image because, for example, you need a customized base image with your preferred OS and JDK enforced by a corporate standard, you can copy this repository and build your own pega-web-ready image based on your preferred base image. When making customizations for your environment, check the [Pega Platform Support Guide Resources](https://community.pega.com/knowledgebase/articles/pega-platform-support-guide-resources) to verify that those changes are supported by your Pega Platform version. + +**Important:** If you choose to build your own image, Pega will continue to offer support for Pega Platform, but problems that arise from your custom image are not the responsibility of Pegasystems. + +To build a custom pega-web-ready image using your preferred OS and JDK, perform the following actions: + +1. Ensure that the base image you selected has $CATALINA_HOME set to the correct Tomcat location. + +2. Create a Dockerfile for your custom pega-web-ready image using your base image and the open-source pega-web-ready Dockerfile code. + +For more information, see [pegasystems/docker-pega-web-ready/Dockerfile](Dockerfile). + +**Note:** You can add any extra environment variables needed in the Dockerfile as per your use-case. + +3. Use the following command to build the custom pega-web-ready image using the base image as an argument. + + ```bash + $ docker build --build-arg BASE_TOMCAT_IMAGE= -t . + ``` + +The system then builds your custom pega-web-ready Docker image. + ## User access and control considerations for this image From 26687263fe3751d4aceb4bc3ae003d51a978e465 Mon Sep 17 00:00:00 2001 From: Kinga Kowalska <120555574+kingakowalska1@users.noreply.github.com> Date: Fri, 29 Nov 2024 11:25:18 +0100 Subject: [PATCH 2/2] BUG-883938 Move Build custom pega-web-ready doc to the main readme MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit From: Peterson, John Sent: Monday, September 23, 2024 2:54 PM To: Kowalska, Kinga ; Kumar, Saurabh Cc: Chikkam, Venkata Satya Gopal ; Saranathan, Raghu ; Talbot, Adam Subject: RE: Documentation to build custom runtime image. Hi Kinga, This looks fine. Thanks, John From: Kowalska, Kinga Sent: Wednesday, September 18, 2024 7:21 AM To: Peterson, John ; Kumar, Saurabh Cc: Chikkam, Venkata Satya Gopal ; Saranathan, Raghu ; Talbot, Adam Subject: RE: Documentation to build custom runtime image. Hi John, I thought the doc that we were incorporating into the README was addressing specifically this issue, that means, creating a web ready image with a client’s customized OS and JDK. Here’s what we have in the PR: If you do not want to use the Pega-provided Docker image because, for example, you need a customized base image with your preferred OS and JDK enforced by a corporate standard, you can copy this repository and build your own pega-web-ready image based on your preferred base image. When making customizations for your environment, check the Pega Platform Support Guide Resources to verify that those changes are supported by your Pega Platform version. Important: If you choose to build your own image, Pega will continue to offer support for Pega Platform, but problems that arise from your custom image are not the responsibility of Pegasystems. To build a custom pega-web-ready image using your preferred OS and JDK, perform the following actions: 1. Ensure that the base image you selected has $CATALINA_HOME set to the correct Tomcat location. 2. Create a Dockerfile for your custom pega-web-ready image using your base image and the open-source pega-web-ready Dockerfile code. For more information, see pegasystems/docker-pega-web-ready/Dockerfile. Note: You can add any extra environment variables needed in the Dockerfile as per your use-case. 3. Use the following command to build the custom pega-web-ready image using the base image as an argument. $ docker build --build-arg BASE_TOMCAT_IMAGE= -t . The system then builds your custom pega-web-ready Docker image. Do we need anything else? If I’m not understanding this correctly, perhaps we could have a chat and clear this up? I could set up a meeting whenever you’re available. Thank you! Kinga From: Peterson, John Sent: Thursday, September 12, 2024 4:19 PM To: Kowalska, Kinga ; Kumar, Saurabh Cc: Chikkam, Venkata Satya Gopal ; Saranathan, Raghu ; Talbot, Adam Subject: RE: Documentation to build custom runtime image. >>https://github.com/pegasystems/docker-pega-web-ready?tab=readme-ov-file#building-a-deployable-docker-image-using-this-web-ready-image These instructions are for taking our provide pega-ready image to build a customized client image. Again, as I explained below this is not really required anymore, because clients can simply take the Pega image to build their own customized client image. I’m looking for the documentation that explains how clients could create a custom ready image with their own OS, JDK, and/or Tomcat implementation. John From: Kowalska, Kinga Sent: Thursday, September 12, 2024 9:55 AM To: Peterson, John ; Kumar, Saurabh Cc: Chikkam, Venkata Satya Gopal ; Saranathan, Raghu ; Talbot, Adam Subject: RE: Documentation to build custom runtime image. Hi John, Do you mean a detailed explanation on how to use the Dockerfile? I thought all of the settings, building commands, image customizations, etc, were explained in the following sections of the readme? First in “Image customizations” and then https://github.com/pegasystems/docker-pega-web-ready?tab=readme-ov-file#building-a-deployable-docker-image-using-this-web-ready-image. Unless you mean something additional that was not covered? Kinga From: Peterson, John Sent: Thursday, September 12, 2024 2:03 PM To: Kowalska, Kinga ; Kumar, Saurabh Cc: Chikkam, Venkata Satya Gopal ; Saranathan, Raghu ; Talbot, Adam Subject: RE: Documentation to build custom runtime image. Hi Kinga, Yeah, I think that works. Do we want to try to explain how they can achieve it? John From: Kowalska, Kinga Sent: Wednesday, September 11, 2024 8:57 AM To: Peterson, John ; Kumar, Saurabh Cc: Chikkam, Venkata Satya Gopal ; Saranathan, Raghu ; Talbot, Adam Subject: RE: Documentation to build custom runtime image. Hi John, Thank you for the detailed explanation, it was very illuminating. 😊 I propose that we write the following: # Using this image Pega offers a publicly available Pega runtime Docker image which includes the prweb.war file, but does not contain Pega rules - for details, see pegasystems/pega on DockerHub and Pega-provided Docker images. Pega builds the pegasystems/pega image from a pegasystems/pega-ready Docker image, a base image that contains an OS (Ubuntu Linux), a Java implementation (Adoptium Temurin JDK11 or JDK17), and an application server (Apache Tomcat) and is customized with Pega-specific configurations. You can use the pegasystems/pega-ready Dockerfile code to customize and build your own web-ready image and then extend it with the Pega .war file of your choice. Docker images provided by Pegasystems are validated and supported by Pega Support. Please let me know if this is sufficient. Thanks! Kinga From: Peterson, John Sent: Friday, September 6, 2024 6:20 PM To: Kowalska, Kinga ; Kumar, Saurabh Cc: Chikkam, Venkata Satya Gopal ; Saranathan, Raghu ; Talbot, Adam Subject: RE: Documentation to build custom runtime image. Is the Pegasystems/pega image the full Docker image, the same one we provide on our repo where you have to request an access token? This is the runtime image. It contains the .war file. Yes, it can be obtained either via Dockerhub or from our repo with access token. Does this mean that we publicly provide the Docker image to install Pega Platform? The installer image is not available on Dockerhub and can only be obtained via downloads-pega.com with a valid access token. The installer image contains the rules and code that need to be loaded into the database prior to starting the runtime image. This discussion is specifically about the runtime image. The runtime image is built on a pega-ready image. The pega-ready image contains: An operating system – Ubuntu Linux A Java implimentation – Adoptium Temurin An application server – Apache Tomcat Pega specific configuration of Tomcat, Java, and Ubuntu. The pega image adds: The pega.war file. At one point we thought it would be helpful to decouple the .war file from the ready image because the .war file was thought to be Pega Infinity agnostic. The general idea was that a client would obtain the full distribution kit from PSOR, which contains the ‘version’ specific .war file. They could run the installer scripts from the distro kit (this was before we even provided an installer image which does this for them). Then then could ‘build’ their Pega image on top of the Ready image to include their Infinity .war file from the kit and any other configuration changes they would like to make (e.g. They may want to bake in their JDBC driver instead of downloading it at startup, and they may want to have a custom java.security policy, etc.). At this time there was also no downloads.pega.com site/registry to obtain the Pega provided images. Since that time the following things happened: 1) We obtained approval to make the .war file available to Dockerhub. 2) IT provided the downloads.pega.com site 3) The .war file has been confirmed to be Infinity version agnostic. 4) There is a requirement by clients to provide their own OS, Java, & App Server. Therefore, if the client just needs to bake in their own JDBC driver, java.security policy, or any other configuration, they can just use the Pega image. The is no longer a reason for clients to use the Ready image (unless they are customizing the .war file itself – which I suppose is possible, but isn’t really supported by the platform) If the client needs to change any or all of the third party open source software packaged inside the Pega image (the runtime image) like the OS, JDK, or Tomcat (e.g. switch to JBoss, Wildfly, or some enterprise Tomcat solution) then they need to be able to build their own Pega image. To build their own image, they first need to build their own ‘ready’ image, thus the value of us providing the Dockerfile that shows how we do that. Once they build their own ‘ready’ image, then they’ll need to layer on the .war, and other specific configurations (JDBC driver, etc.) to create their own Pega runtime image. John From: Kowalska, Kinga Sent: Wednesday, August 28, 2024 5:57 AM To: Peterson, John ; Kumar, Saurabh Cc: Chikkam, Venkata Satya Gopal ; Saranathan, Raghu Subject: RE: Documentation to build custom runtime image. Hi John, I don’t think I entirely follow the messaging. Is the Pegasystems/pega image the full Docker image, the same one we provide on our repo where you have to request an access token? Does this mean that we publicly provide the Docker image to install Pega Platform? If this is the same image, I’m confused about the difference between the .war file being in the Docker image and the Pega Platform rules being there. Is this a four step process like this: Tomcat image extended to  pega-web-ready which has preliminary rules but not the .war file and Pega Platform rules and extends to  Pegasystems/pega that has a .war file but not Pega Platform rules  platform/pega image available in the private repository with everything needed to deploy Pega Platform? Thanks, Kinga From: Peterson, John Sent: Tuesday, August 20, 2024 9:40 PM To: Kowalska, Kinga ; Kumar, Saurabh Cc: Chikkam, Venkata Satya Gopal ; Saranathan, Raghu Subject: RE: Documentation to build custom runtime image. Hi Kinga, I spoke to Dave Casavant, and we feel that since we are now providing a full “pega” image, there is no longer a need to mention the option of building from “pega-ready” outside of customization because clients could just take the “pega” image and not have to provide their own .war file. It still provides value, because clients can see what needs to be done to build their own image if they don’t want to use ours. So I’d update the following section to be something like (probably needs some word smithing) # Using this image Pega offers a publicly available Docker image which includes the prweb.war file - for details, see [pegasystems/pega on DockerHub][pegasystems/pega]. It does not include Pega Platform rules. The Pega image extends a web-ready Docker image. The [pegasystems/pega-ready](https://hub.docker.com/r/pegasystems/pega-ready) Docker image extends a customized Tomcat base image with either JDK11 or JDK17 and contains required components that allow you to run a Pega Platform on your deployment nodes. This ready image can be used as an example base image for clients who need to build a custom image. Docker images provided by Pegasystems are validated and supported by [Pega Support](https://community.pega.com/support). John From: Kowalska, Kinga Sent: Tuesday, August 20, 2024 6:11 AM To: Peterson, John ; Kumar, Saurabh Cc: Chikkam, Venkata Satya Gopal ; Saranathan, Raghu Subject: RE: Documentation to build custom runtime image. Hi John, I created the following PR to move the doc to the readme: https://github.com/pegasystems/docker-pega-web-ready/pull/222 Please let me know if this is what you had in mind. I made some minor corrections to some links that weren’t working in the introduction as well. Best regards, Kinga Kowalska | Principal Technical Writer | Pegasystems Inc. Email: kinga.kowalska@pega.com | pega.com From: Peterson, John Sent: Monday, August 19, 2024 2:14 PM To: Kowalska, Kinga ; Kumar, Saurabh Cc: Chikkam, Venkata Satya Gopal ; Saranathan, Raghu Subject: RE: Documentation to build custom runtime image. Hi Kinga, I’m fine with you creating the PR, thanks! Also, yes, I can review the new docs.pega.com article. Thank you, John From: Kowalska, Kinga Sent: Monday, August 19, 2024 8:03 AM To: Peterson, John ; Kumar, Saurabh Cc: Chikkam, Venkata Satya Gopal ; Saranathan, Raghu Subject: RE: Documentation to build custom runtime image. Hi John, Perhaps it would be better if I created the pull request and integrated the current separate doc into the readme? This way I can quickly deal with commits and changes and you and Saurabh can approve the end product for technical accuracy. As for the docs.pega.com articles, I’m currently working on a global article that explains the Pega Git hub resources, which includes the Docker pega-web-ready repository. This additional article would be linked with the current information we have about custom images, which could be updated accordingly. Do you think you would be able to review the “Understanding Pega GitHub resources” article when it’s complete? Thanks, Kinga From: Peterson, John Sent: Monday, August 19, 2024 1:33 PM To: Kumar, Saurabh ; Kowalska, Kinga Cc: Chikkam, Venkata Satya Gopal ; Saranathan, Raghu Subject: RE: Documentation to build custom runtime image. Thank Saurabh, Wow, I couldn’t find it. I think the current location is hard to find and it is not referenced by any other document (that I could find). To fix these issues, please move it to here: https://github.com/pegasystems/docker-pega-web-ready/tree/aa3b38387e1604f174ea52ffa1d890a5f8abf182?tab=readme-ov-file#image-customizations Kinga, can you review Saurabh’s PR when it’s ready? We might need to update the wording of the intro to mention this new option. Also the docs.pega.com references and mentions of custom images, could probably be reviewed as well, what do you think? Thanks, John From: Kumar, Saurabh Sent: Monday, August 19, 2024 1:10 AM To: Peterson, John Cc: Chikkam, Venkata Satya Gopal ; Saranathan, Raghu Subject: Re: Documentation to build custom runtime image. Hi John, Yes, the documentation can be accessed at https://github.com/pegasystems/docker-pega-web-ready/blob/master/docs/Building-Image-With-Own-OS-And-JDK.md -Saurabh From: Peterson, John Date: Friday, 16 August 2024 at 11:32 PM To: Kumar, Saurabh Cc: Chikkam, Venkata Satya Gopal , Saranathan, Raghu Subject: Documentation to build custom runtime image. Hi Saurabh, As part of the FIPS work, in which we now publish detemplize as an image for usage by the builder pattern, did we ever update the image build documentation to explain how to bring your own OS & JDK? John --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 61dede5b..0be8392f 100644 --- a/README.md +++ b/README.md @@ -7,9 +7,9 @@ Pega Platform is a distributed web application for customer engagement, customer # Using this image -The [pegasystems/pega-ready](https://hub.docker.com/r/pegasystems/pega-ready) Docker image extends a customized Tomcat base image with either JDK11 or JDK17 and contains required components that allow you to run a Pega Platform on your deployment nodes. It does not include Pega Platform rules. This image is web-ready for clients to build a final image that includes the Pega .war file of your choice. +Pega offers a publicly available Pega runtime Docker image which includes the prweb.war file, but does not contain Pega rules - for details, see [pegasystems/pega on DockerHub][pegasystems/pega] and [Pega-provided Docker images](https://docs.pega.com/bundle/platform/page/platform/deployment/client-managed-cloud/pega-docker-images-manage.html). Pega builds the `pegasystems/pega` image from a [pegasystems/pega-ready](https://hub.docker.com/r/pegasystems/pega-ready) Docker image, a base image that contains an OS (Ubuntu Linux), a Java implementation (Adoptium Temurin JDK11 or JDK17), and an application server (Apache Tomcat), and that is customized with Pega-specific configurations. You can use the `pegasystems/pega-ready` Dockerfile code to customize and build your own web-ready image and then extend it with the Pega .war file of your choice. -Pega offers an alterative, full image which *includes* the .war file - for details, see [pegasystems/pega on DockerHub][pegasystems/pega] and [Pega-provided Docker images](https://docs.pega.com/bundle/platform/page/platform/deployment/client-managed-cloud/pega-docker-images-manage.html). Docker images provided by Pegasystems are validated and supported by [Pega Support](https://community.pega.com/support). +Docker images provided by Pegasystems are validated and supported by [Pega Support](https://community.pega.com/support). ## Image customizations