Constellation AppStatic service on Docker

Note:

Setup the service requires good understanding of containers and docker, https certificates, domain names and network server configuration. This is usually a task done by a sys. admin.

In particular there should be good understanding of Docker volumes and Docker mounts.

Before you begin

Prepare for the Installation

  1. Ensure that you have the Docker command line interface installed on your on-premises environment.
  2. Obtain an API key from the Pega Digital Delivery site. For more information please check this page
  3. Prepare docker authentication. For more information please check this page

Downloading the constellation appstatic service

  1. Log in to Pega's Docker repository from your terminal or browser.

    For example : docker login pega-docker.downloads.pega.com

  2. Now pull the highest version appstatic docker image.

    For example : docker pull pega-docker.downloads.pega.com/constellation-appstatic-service/docker-image:1.0.9-20230111194246

Starting the constellation appstatic service

The C11n App-Static service is used in many different deployments; Docker, Compose, K8s, behind a LB with cert, using local disk persistence, using Cloud cross region NFS persistence, ... . This requires a number of run params to customise the behavior. Most params have suitable defaults, and do not need to be specified. Here are the typical params that may be customised:

Mandatory

param description
urlPath The url path that the service is deployed on – should match load balancer or router traffic routing
root Disk root of image in container; leave at /usr/src/app/dist
port The port that the container is mapping the connection to

release 1.31 only

param description
skipTokenPermissionCheck Set true for authentication to continue if the JWT does not include the operator-permission claim

The 'skipTokenPermissionCheck' exists at version 1.31 to go in-step with these Infinity hotfixes: 23.1.0 hfix (HFIX-C336), 23.1.1 hfix  (HFIX-C315), 23.1.2 hfix (HFIX-C335), 23.1.3 hfix (HFIX-C334), 23.1.4 hfix (HFIX-C333), 24.1.0 hfix (HFIX-C340), 24.1.1 hfix (HFIX-C338), 24.1.2 hfix (HFIX-C337), 24.2.0 hfix (HFIX-C339) THis additional param is to disable strict checking of the read/write permission in the JWT passed from the browser and Infinity. This flag is needed for the period of time between installing the service update and updating Infinity with JWT permission hfix:

https certificates

This is only required if the cert is to be put on the service. Puttting the cert on the LB is the recommended path.

param description
httpsKey key file name
httpsCert cert file name

Folder holding key and cert file should be mounted with -v to path /host_folder.

Volume mount

Where an external disk is being used for persistence of customer assets, that should be mounted through a volume mount, to path /usr/src/app/dist/customers

Simplest launch

  1. Start the service by entering

    docker run -p 3000:3000 --name c11n-appstatic pega-docker.downloads.pega.com/constellation-appstatic-service/docker-image:1.0.9-20230111194246 port=3000 root=/usr/src/app/dist urlPath=/c11n-appstatic

  2. This starts the service listening on port 3000, with url path /c11n-appstatic . Internal disk space is used for persistence. This is the strongly recommended start point.

Launch with customer certificate

  1. Start the service by entering

    docker run -p 3443:3443 -v /usr/abc/certs:/host_folder --name c11n-appstatic pega-docker.downloads.pega.com/constellation-appstatic-service/docker-image:1.0.9-20230111194246 port=3443 root=/usr/src/app/dist urlPath=/c11n-appstatic httpsKey=afile.key httpsCert=bfile.cert

  2. This starts the service listening on port 3443 for https, with cert bfile.cert. The domain in the cert must match the domain the the service is on. This is not recommended. It is easier to put the cert on the LB.

Launch with external persistence

  1. Start the service by entering

    docker run -p 3000:3000 -v /someexternaldrive:/usr/src/app/dist/customers --name c11n-appstatic pega-docker.downloads.pega.com/constellation-appstatic-service/docker-image:1.0.9-20230111194246 port=3000 root=/usr/src/app/dist urlPath=/c11n-appstatic

  2. This starts the service listening on port 3000, with url path /c11n-appstatic . External drive /someexternaldrive used for persistence of customer assets.

Service ping and health check

  1. You can perform a ping check on the service at protocol://domain:port/c11n-appstatic/v860/ping
  2. You can perform a health check on the service at protocol://domain:port/c11n-appstatic/v860/healthcheck
  3. Now you can set the ConstellationSvcURL DSS to the above url to use the service.
  4. After setting the DSS and saving it, you can see post calls in the docker logs.

Demo Example