Installing Workflow Process Service on Docker

1. Installing prerequisites

2. Configuring the docker-compose YAML file

Create a folder on your local computer, such as sample/folder, where you will run Docker Compose. In the new folder, create a new file named docker-compose.yml. Get the docker-compose.yml file from icp4a/workflow-process-service-samples and copy the contents into your new file. You can choose to install the Workflow Process Service Authoring environment or the Workflow Process Service Server environment by uncommenting the appropriate line at the beginning of the file.

Before you run docker compose up, you must make the following changes to the YAML file:

1. Configure either Workflow Process Service Authoring or Workflow Process Service Server, by uncommenting the image parameter. For example, the section might look similar to:

   workflow:
       # uncomment the following line if you plan to run the Authoring environment
       image: cp.icr.io/cp/cp4a/workflow-ps/workflow-ps-authoring:22.0.2
       # ...or uncomment the following line if you plan to run the Process Server environment
       # image: cp.icr.io/cp/cp4a/workflow-ps/workflow-ps-server:22.0.2

2. To successfully connect to your PostgreSQL database, set the following environment variables:

   Environment Variable	Description
   DB_SERVER_NAME	Hostname to connect to the PostgreSQL database.
   DB_SERVER_PORT	Port to connect to the PostgreSQL database.
   DB_DATABASE_NAME	Name of the database.
   DB_USERNAME	User to authenticate the connection to the PostgreSQL database. The database must contain a schema with the same name as DB_USERNAME.
   DB_PASSWORD	Password to authenticate the connection to the PostgreSQL database.

3. If PostgreSQL database is using shared_buffers, mount the root certificate that was used to sign the PostgreSQL server certificate, so the client can verify that the server's leaf certificate was signed by its trusted root certificate. This root certificate must be mounted in /shared/custom/cert-trusted/db_root.crt. This file must have the appropriate ownership and access rights to allow dba-user (userId=50001) to read it. To set required ownership and access rights, run the following commands:

   chown 50001:0 db_root.crt
   chmod 400 db_root.crt

4. Create the database for Workflow Process Service.
   1. Create a file named create-wps-database.sql and copy it to your PostgreSQL server.
   2. Configure your database by using the following commands:

      -- create user wpsdmin
      CREATE ROLE wpsadmin PASSWORD 'wpsadmin_password' SUPERUSER CREATEDB CREATEROLE INHERIT LOGIN;
      
      -- wpsdb
      CREATE DATABASE wpsdb OWNER wpsadmin ENCODING UTF8;
      GRANT ALL PRIVILEGES ON DATABASE wpsdb to wpsadmin;
      \c wpsdb;
      CREATE SCHEMA IF NOT EXISTS wpsadmin AUTHORIZATION wpsadmin;

      In this example:
      • wpsdmin is the username that Workflow Process Service uses to connect to the database.
      • wpsadmin_password is the password that Workflow Process Service uses to connect to the database.
      • wpsdb is the database name for the Workflow Process Service database. This name is case-sensitive.
   3. Run the following commands on the PostgreSQL server:

      su - postgres
      psql -f create-wps-database.sql

5. Configure your passwords. By default, passwords are randomly generated. You can set your own passwords by mounting a file at /shared/custom/env/server.env. For example, the file might look like:

   # OIDC client secret, this secret must not be modified after the very first start of the environment
   CLIENT_SECRET={xor}EQgVNgYyFm8SGw==
   # Admin user password
   ADMIN_PASSWORD={xor}BggabwU1NGoRGw==
   # FUNCTIONAL_USERNAME and FUNCTIONAL_PASSWORD are designed for API invoke. It is used to call automation service by default.
   FUNCTIONAL_USERNAME=NmY0ZmRjNm
   FUNCTIONAL_PASSWORD={xor}BRsWbQUbETYRJQ==
   # The password used to access the keystore file when SSL is enabled.
   SSL_KEYSTORE_PASSWORD={xor}EggJNQU1GmwFCA==

   Make sure the user dba-user (id=50001) has access to these files:

   chown 50001:0 *.env
   chmod 400 *.env

   To mount your own server.env file on an environment that relies on generated passwords, you must start from a copy of the file located at /shared/custom/env/server.env. The CLIENT_SECRET password is unchanging and you must reuse the same CLIENT_SECRET value as the one that was generated in /shared/custom/env/server.env. If you rely on the generated keystore and truststore, reuse the same SSL_KEYSTORE_PASSWORD value as the one which was generated in /shared/custom/env/server.env.
6. Configure your keystore and truststore. If you want to provide your own keystore and truststore, you can mount them in PKCS12 format to the /shared/custom/tls/key.p12 and /shared/custom/tls/trusts.p12 locations. For example:

       volumes:
         - ./config/tls/key.p12:/shared/custom/tls/key.p12:Z
         - ./config/tls/trusts.p12:/shared/custom/tls/trusts.p12:Z 

   To mount these files, dba-user (id=50001) must have access to these files:

   chown 50001:0 *.p12
   chmod 400 *.p12

   You must also either provide the keystore and truststore password as documented in the previous step, or provide the password through the SSL_KEYSTORE_PASSWORD environment variable. If you do not provide your own keystore and truststore, they are automatically generated when IBM Workflow Process Service is started. Upon start, when the truststore is generated, all PEM certificates that are found in /shared/custom/cert-trusted folder are added to the truststore.
   Note: The truststore file must have either the .pem or .crt file format.
7. Configure your hostname. You must configure the EXTERNAL_HOSTNAME environment variable to match the hostname that you use to remotely access the Workflow Process Service Rest API, Workplace, and, when you are running the Workflow Process Service Authoring environment, the IBM Business Automation Studio.

3. Running your environment

1. If your operating system is Linux and uses Docker as the container engine, make sure that the container has read and write permissions in the folder where you want to run docker compose. Because the container user ID is 50001 and belongs to the root group, you can use the following command to change the folder's permissions:

   sudo chown 50001:0 current_sample_folder

2. Connect to the Docker repository containing the Docker image.
   1. Log in to MyIBM Container Software Library with the IBMid and password that is associated with the entitled software.
   2. In the Container software library tile, verify your entitlement on the View library page, and then go to Get entitlement key to retrieve the key.
   3. Use the command docker login cp.icr.io and log in to the entitled registry with your entitlement key.
3. If you want to use your local registry, run the following commands:

   docker pull cp.icr.io/cp/cp4a/workflow-ps/workflow-ps-authoring:<tag>
   docker pull cp.icr.io/cp/cp4a/workflow-ps/workflow-ps-server:<tag>
   
   docker login <server>
   
   docker tag cp.icr.io/cp/cp4a/workflow-ps/workflow-ps-server:<tag> <server>/workflow-ps-server:<tag>
   docker tag cp.icr.io/cp/cp4a/workflow-ps/workflow-ps-authoring:<tag> <server>/workflow-ps-authoring:<tag>
   
   docker push <server>/workflow-ps-server:<tag>
   docker push <server>/workflow-ps-authoring:<tag>

   where:

   • <server> is the host of the Docker image registry that you want to use to pull the images. For example, myregistry.local:5000 or localhost:8080 for a self-hosted registry.
   • <tag> is the corresponding version or interim fix's tag in the form of <release>-IFxxx. For example, 22.0.2-IF001.
4. If you completed the previous step, ensure that the correct image is configured for either Workflow Process Service Authoring or Workflow Process Service Server in the docker-compose.yml file. The format of the parameter looks similar to:

   <server>/workflow-ps-server:<tag>
   <server>/workflow-ps-authoring:<tag>

5. Start your environment Workflow Process Service by running the command docker compose up in the folder where the docker-compose.yml file is located.
6. Monitor the output of the docker compose up command. The server is up when you see a message similar to the following:

   The system maintenance monitor is determining if maintenance is required. The system is in an OK state.

4. Verifying your installation

1. Go to https://external_hostname:external_https_port/Workplace to launch the hiring sample process.
2. Go to https://external_hostname:external_https_port/oidc/endpoint/ums/registration to verify that OIDC clients are registered successfully.
3. To get the access URLs, admin username, and admin password, run the following command:

   docker exec <container_name> /scripts/post-deployment.sh

   Follow the links in the output of the command to access Workplace and Business Automation Studio.
4. To get information about your environment variables, run the following command:

   docker exec <container_name> /scripts/get-env-info.sh

Troubleshooting

During Docker Compose startup, you might see some login failures in the Docker logs. These login failures are harmless and you can ignore them. They happen because the event manager keeps checking the login status and waits for the client registration before it starts.

Permission denied when running docker compose up

mkdir: cannot create directory '/shared/custom/env': Permission denied
pc exited with code 1

Follow these steps:

1. Run docker volume ls to check the created volumes, then find the volume whose name contains production_workflow_runtime_data. Check the details of the volume.
2. The device that is output by docker volume inspect production_workflow_runtime_data is resolved to an absolute path if docker compose is run successfully. If the output device is not an absolute path, you must upgrade docker compose to the latest version because it can't resolve relative paths.
   • The following is an example of docker compose correctly resolving the absolute path of the device:

     docker volume inspect < volume name >
     [
         {
             ......
             "Options": {
                 "device": "/home/tester/ci.docker.baw-designer-mini/test/tryandbuy-compose/persistence/basic",
                 ...
             },
            ......
         }
     ]

   • The following is an example of docker compose failing to resolve the absolute path of the device:

     docker volume inspect < volume name >
     [
         {
             ......
             "Options": {
                 "device": "./",
                 ...
             },
            ......
         }
     

Cannot access Workplace or Business Automation Studio in Chrome

Out of memory error using Docker Desktop

IBM_JAVA_OPTIONS="-Xmx1563M"