Skip to main content


         This documentation site is for previous versions. Visit our new documentation site for current releases.      
 

Pega-provided Docker images

Updated on October 4, 2022

In client-managed cloud environments, clients obtain the required licenses to download and use Pega-provided Docker images to deploy Pega Platform in a Kubernetes environment of their choice.

Client-managed cloud information on Pega Community Client-managed cloud information on Pega Community Client-managed cloud information on Pega Community Client-managed cloud information on Pega Community Client-managed cloud information on Pega Community

Deploying Pega Platform using Kubernetes requires that you install Pega software files into a database that is available to the deployment. Pega-provided several Docker images that work together to deploy Pega software on nodes and a database instance running in your preferred cloud environment. Download required Docker images to your local system from the Pega-managed Docker repository, and tag them, and then upload them to your preferred Docker image repository.

A Pega deployment includes processes that prepare a split-schema configuration in which Pega rules and data objects reside on separate schemas. The process copies the Pega software into your rules schema. Pega provides separate Docker images to run a Tomcat-based web application, a backing service that runs Elasticsearch-based searches, and a Hazelcast cluster.

Pega-provided Docker images overview

After you obtain the required access download the required Pega Docker images from the Pega host site.

List of the Pega-provided Docker images:

Image NameDescriptionVersion details
platform/pegaDeploys Pega Platform with its customized version of the Tomcat application server.Pega provides a pega Docker image for minor versions and patch versions of Pega Platform. To stay current with Pega releases, use the latest available image.
platform/installerA utility image Pega provides to install or update the Pega-specific rules and database tables in the “Pega” database that you have configured for your deployment.Pega provides a pega-installer image for minor versions and patch versions of Pega Platform. To stay current with Pega releases, use the latest available installer image to install or update your Pega software.
platform-services/search-n-reporting-serviceDeploys a cluster that runs search and reporting functions on dedicated, backing service nodes. This Docker image contains Pega Search and Reporting Services (SRS), with which you optimize Elasticsearch processing in your Pega deployment.

Pega Platform version 8.6 and later support the backing service feature that runs independently of your web server nodes.

For an overview of setting up SRS-based search in Pega Platform and using Indexed classes for SRS, see the appropriate section in Using full-text search based in Elasticsearch.

Pega provides SRS Docker image versions starting at 1.12.0; Pega certified these images against Elasticsearch versions 7.10.2 and 7.16.3. To stay current with Pega releases, use the latest available SRS image--1.17.10 or later.
platform/clustering-serviceDeploys the required clustering service, Hazelcast for the caching capabilities in Pega Infinity as a backing service. This Docker image contains the Hazelcast clustering Service.

Pega Platform versions 8.6 and later support the client-server Hazelcast model. This model supersedes the embedded deployment, which is deprecated in 8.7 and later and do not use the embedded model for new deployments.

To stay current with Pega releases, use the latest available a Hazelcast service Docker Image that is tagged with version 1.0.3 or later.

Determining which Dockers images to use for your deployment

Pega uses a standard naming practice of hostname/product/image:tag.

When you choose a Pega Platform version for your downloaded Docker images, use the same version tag for each of the images that you download. For the platform/installer/image:tag image, the :tag represents the version of Pega that you want to install. For example, the tag :8.7.1 installs Pega Platform version 8.7.1.

For platform/pega and platform/search images, Pega also offers an image with a version tag appended with a date stamp that uses the pattern pegaVersion-YYYYMMDD to indicate the version and the date when Pega built the image. For example, if you pull the platform/pega that has the tag pega:8.5.1-20201026, it indicates that Pega built this 8.5.1 image on October 26, 2020. Using the version tag without the date stamp points to the most recently built image for that version.

The date stamp confirms that the image you download includes the changes that Pega engineering commits to the repository by using pull requests that have the date stamp date. While Pega builds the most current patch version of each minor release once daily, Pega makes the last five daily-built images available for client downloads. After Pega releases a new patch version, the prior patch version no longer receives daily builds with a date stamp tag.

For Pega Platform 8.6 and later, Pega supports a new client-server deployment model using a cluster of nodes running Hazelcast as server, to which the Pega nodes connect as a client. This new client-server deployment model improves the stability for Pega Platform deployments that use a large number of nodes because it introduces independent scalability for both servers and clients in Pega Platform. Because of the inherent stability and scalability of this model, clients deploying Pega Platform 8.6 and later should adopt this client-server model using Hazelcast. Future Pega Platform releases will not support embedded Hazelcast deployments. To deploy Pega Platform and Hazelcast by using this client-server deployment model, download, and then push the Clustering Service Docker image, platform/clustering-service, to your Docker repository, and then reference it with the Hazelcast subchart under the Pega-specific Helm chart. For the platform/clustering-service image, the image tag represents the version of Clustering Service that you want to install, for example, the :1.0.3 tag installs clustering-service version 1.0.3.

The Docker image platform-services/search-n-reporting-service, used with the SRS-specific backing sub-charts provides Pega backing services. For more details, including an overview of how to configure the Pega backing services, see the readme file in the BackingServices Helm chart. The SRS subchart deployment provisions the latest generation of search and reporting capabilities in Pega Platform. This service provides the search service feature and replaces the previously provided platform/search image-based Elasticsearch deployment. The Docker image tagging format is different for backing services compared to the Pega Platform images and does not follow the date stamp pattern. For installing or updating Pega Infinity 8.6, use the SRS image, 1.17.10 or later.

Requesting access to Pega-provided Docker images

You can request access to the Pega-provided image repository to download the Docker images that Pega Platform deployments require. You must request access credentials to obtain an access key that you use to download Docker images maintained in the Pega site. Pega provides access credentials only to clients that have an appropriate support role in an organization that already works with Pega. Pega partners are not allowed to request an access key on behalf of their customer to obtain the Pega-provided Docker images.

Only clients that have appropriate access can log in to the image repository and download Docker images that are required to install the Pega Platform into your database.
  1. In the browser of your choice, navigate to Pega Community.
    From here, request access, and after Pega provides your access key, you can log in to the image repository, and then download your preferred Docker images.
  2. Log in with your registered credentials.
    If you have not registered, do so before continuing.
  3. Navigating the top banners, and then select Support > Download Pega Software.
    Download Pega Software link
    Navigate to the Pega software downloads page using the link under the Support tab
  4. In the Run the Pega Platform in a container area in the upper-right of the Download Pega software page, click Request Access.

    Prompt to complete your access request
    Initiate a request granting you access to dowload the required Docker images.

    After completing your access request, you receive a confirmation that you will soon receive an email with your access information.

    5. Confirmation of your access request
    Pega sends an acknowledgment that you have requested an access key."
  5. Open the email which contains your credentials.
    Email containing your User ID and corresponding Access Key
    Your User ID and corresponding Access Key are included in the email.
  6. Save your User ID and access key to a text file in a local file. Use a credential file, such as a gpg2 key, to ensure that you pass it to your Docker login command, to ensure that your bash history or logs do not display your credentials.
    For details, see Credentials management.
What to do next: With your access key, you can pull images from the Pega Docker image repository that corresponds to your type of image.

Manage downloaded Docker images

To deploy your client-managed cloud environments, after you have appropriate licenses, manage your downloaded Docker images in your repository and make them available to the Kubernetes environment in which you deploy Pega Platform. These images do not expire, and you can keep them in your repository for as long as necessary.

Before you begin: Using access credentials to the Pega Docker image repository, log in, download each required image, retag each image appropriately, and then upload each image to your own Docker registry. Pega supports the following popular Docker image repositories:

If you are setting up a Docker registry for the first time, review the Docker article, Deploy a registry server.

Depending on your Kubernetes configuration and registry of choice, you might need to fully qualify your image before you complete your deployment. For example, to access an image that you tagged as pega/platform:latest and pushed to yourregistry.example.com, reference your image in the Pega configuration files as yourregistry.example.com/pega/platform:latest. For details about using a private Docker registry, see How to use your own registry article on Docker Blog.

Use the same Docker image tag for your deployment to ensure that you download compatible images. The following steps exemplify the sequence and command-line syntax that you use to reference your required images as you pull, tag, and then push each image.
  1. In a Linux bash shell that has root privileges or a Windows PowerShell running with administrator privileges, navigate to the folder where you saved the file that contains your encrypted access key.
  2. Log into the Pega-managed Docker image repository, including your Pega-provided UserID:
    $ cat <localfilepath>\<platform>-demo\<access-key-filename>.txt | docker login pega-docker.downloads.pega.com --username=<reg-XXXXX> --password-stdin
Login Succeeded
  3. Use a Jfrog API query to view the list of Pega-provided Docker image repositories that you can access by specifying the Pega-provided accessKey you received in :
    $ curl -X GET https://pega-docker.downloads.pega.com/v2/_catalog -H "X-JFrog-Art-Api:[accessKey]"
    Based on the image name descriptions in , you now must select an image within each repository you can access. In general, you have to choose a Docker image from within each of the following repositories:
    • platform/pega - provides the Pega-provided customized version of the Tomcat application server for your deployment.
    • platform/pega-installer - provides an installation, patch, or update containing specific rules and database tables in the database in which you configured your deployment.
    • platform-services/search-n-reporting-service - provides a cluster that runs the backing service for your deployment.
    • platform/clustering-service - provides a cluster that runs the Hazelcast service for your deployment.
    Unless you have deployments running specific versions, your best choice for choosing an image within each repository is usually the latest version of a Docker image.
  4. Use a Jfrog API query to view the list of Docker images from within each available repository by specifying an available repository name and the Pega-provided accessKey:
    $ curl -X GET "https://pega-docker.downloads.pega.com/v2/[repository name]/tags/list" -H "X-JFrog-Art-Api:[accessKey]"
    Note the image name that you want. You will use the image details in the following set of commands.
  5. Download your preferred version of the pega image to your local system by specifying the version tag:
    $ docker pull pega-docker.downloads.pega.com/platform/pega:8.7.0
Digest: <encryption verification>
Status: Downloaded pega-docker.downloads.pega.com/platform/pega:8.7.0
  6. Retag the pega image for your deployment with a customized tag that includes your Docker registry host name and a name that is useful to your organization.
    $ docker tag pega-docker.downloads.pega.com/platform/pega:8.7.0 <Registry host name:Port>/my-pega:8.7.0
  7. Push the retagged my-pega image to your registry:
    $ docker push <Registry host name:Port>/my-pega:8.7.0
  8. Download your preferred version of the pega-installer image to your local system, by specifying the version tag:
    $ docker pull pega-docker.downloads.pega.com/platform/installer:8.7.0
Digest: <encryption verification>
Status: Downloaded pega-docker.downloads.pega.com/platform/installer:8.7.0
  9. Retag the pega-installer image for your deployment with a customized tag that includes your Docker registry host name and a name that is useful to your organization:
    $ docker tag pega-docker.downloads.pega.com/platform/installer:8.7.0 <Registry host name:Port>/my-pega-installer:8.7.0
  10. Push the retagged my-pega-installer image to your registry:
    $ docker push <Registry host name:Port>/my-pega-installer:8.7.0
  11. Download a version of the search-n-reporting-service image to your local system by specifying the version tag as shown in the following example:
    Pegarecommends using the latest available SRS image - 1.17.10 or later.
    $ docker pull pega-docker.downloads.pega.com/platform-services/search-n-reporting-service:1.17.10
Digest: <encryption verification>
Status: Downloaded pega-docker.downloads.pega.com/platform-services/search-n-reporting-service:1.17.10
  12. Retag the search-n-reporting-service image for your deployment with a customized tag that includes your Docker registry host name and a name that is useful to your organization:
    $ docker tag pega-docker.downloads.pega.com/platform-services/search-n-reporting-service:1.17.10 <Registry host name:Port>/my-pega-srs:1.17.10
  13. Push the retagged my-pega-srs image to your registry:
    $ docker push <Registry host name:Port>/my-pega-srs:1.17.10
  14. Download a version of the platform/clustering-service image for Hazelcast to your local system by specifying the version tag as shown in the following example:
    Pega recommends using a Hazelcast service Docker Image that is tagged with version 1.0.3 or later.
    $ docker pull pega-docker.downloads.pega.com/platform/clustering-service:1.0.3
Digest: <encryption verification>
Status: Downloaded pega-docker.downloads.pega.com/platform/clustering-service:1.0.3
  15. Retag the platform/clustering-service image for your deployment with a customized tag that includes your Docker registry host name and a name that is useful to your organization:
    $ docker tag pega-docker.downloads.pega.com/platform/clustering-service:1.0.3 <Registry host name:Port>/my-pega-clustering-service:1.0.3
  16. Push the retagged platform/clustering-service image to your registry:
    $ docker push <Registry host name:Port>/my-pega-clustering-service:1.0.3

Build custom Docker images for your deployments

Pega supports clients deploying and managing Kubernetes with specific Docker needs to customize Docker images to support your Pega Platform deployments.

Pega provides dockerfiles you can use to build a set of custom Docker images if your organization enforces a corporate standard as to which operating system and Java libraries to include in your Docker images. Pega provides Docker image with Ubuntu as the operating system because of licensing restrictions around many commonly used operating systems; however, before you customize your images, check the Platform Support Guide to verify that your changes, including your operating system and Java libraries are supported by your Pega Platform version. When you deploy using your own custom image, Pega will continue to offer support for Pega Platform, but problems that arise from your custom image are not the responsibility of Pega.

If you build your own Docker images, you do not have to download the Pega-provided Docker images listed in the table to complete your deployment. You must be familiar with Docker commands to build your own images. As a starting point, see Dockerfile reference.

After you build customized Docker images for use in a deployment of Pega Platform, Pega requires you to place them in your non-public, privately-managed Docker registry since it includes proprietary Pega files.

After you complete a deployment using a set of these custom images, it is your responsibility to keep your Pega up to date by downloading Pega software distributions and creating new custom images for patches and minor version updates.

Build a Pega installer image

To prepare an installation image, use a Pega-provided Dockerfile image that is designed to be used with a Pega Platform distribution that you have downloaded. You must use this custom image to complete a database installation of Pega Platform rules as part of your deployment. For complete details, see Building a Pega Platform installer Docker image.

Build a Pega web image

To prepare a Pega web image, use a Pega-provided Dockerfile image that extends a customized Tomcat base image and contains required components that allow you to run Pega Platform on your deployment nodes. For complete details, see Pega Docker Image.

Build a Pega Search and Reporting Service image

To prepare a Pega Search and Reporting Service (SRS) image, use the Pega-provided SRS-builder Dockerfile image. For complete details, see Building a Search and Reporting Service(SRS) docker image.

Tags

Pega Platform 8.7 Client-managed Cloud

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Visit the Support Center

Did you find this content helpful?

Yes
No

Want to help us improve this content?
Suggest an edit

We'd prefer it if you saw us at our best.

Pega.com is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us