Installing Workflow Process Service
Workflow Process Service can be run in the Workflow Process Service Authoring environment or the Workflow Process Service Server environment. The authoring environment comes with IBM® Business Automation Studio and allows you to create, maintain, and edit Business Automation Workflow. Both environments run Business Automation Workflow and have IBM Workplace as the front-end user interface. Each of these environments has the same prerequisites but they have unique Docker images.
For details, see IBM Workflow Process Service.
1. Installing prerequisites
- Check the detailed system requirements.
- Install Docker Engine 19.03 or later through Install Docker Engine. Information about supported Linux operation system versions is available through the link.
- Install Docker Compose 1.27.3 or later through Install Docker Engine
- Prepare PostgreSQL database. To make sure the PostgreSQL database is configured
correctly for the customer workload, update the following parameters in the
postgresql.conf
file of the database server:Parameter Setting Description shared_buffers
Minimum 1024 MB PostgreSQL performance tuning recommends using 25% of the memory for the shared buffer. Updates to the Linux kernel configuration might also be required. For more information, see the PostgreSQL tuning guides. work_mem
Minimum 20 MB This parameter applies to each session and many user sessions can cause large memory usage. This memory is critical because it is used for sort operations. The running time can increase significantly if the value is set too low. For example, the running time may be over an hour for toolkit deployments. max_prepared_transactions
For example, 200 This value should be at least as large as the max_connections
setting.max_wal_size
For example, 6 GB For larger workloads, the default value must be increased. To check if an increase is required, see the PostgreSQL server log files. log_min_duration_statement
For example, 5000 This optional parameter allows you to log statements that exceed the specified running time to identify bottlenecks and potential tuning areas. This value is measured in milliseconds. For example, a value of 5000 corresponds to 5 seconds. - You can enable full text search and dashboard support by activating Process Federation Server (PFS) runtime in Process Federation Server. To activate Process Federation Server, you must get Elasticsearch 7.8 or later. Before you start installation, set up an Elasticsearch node or cluster. For more information, see Enabling full text search and dashboard support in Workplace.
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:
-
Choose the Workflow Process Service Authoring environment or the Workflow Process Service Server environment.
- 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. - 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-truststoreed/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
- Create the database for Workflow Process Service.
- Create a file named create-wps-database.sql and copy it to your PostgreSQL server.
- Configure your database by using the following commands:
In this example:-- 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;
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.
- Run the following commands on the PostgreSQL server:
su - postgres psql -f create-wps-database.sql
- 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:
Make sure the user# 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==
dba-user (id=50001)
has access to these files:
To mount your ownchown 50001:0 *.env chmod 400 *.env
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. TheCLIENT_SECRET
password is unchanging and you must reuse the sameCLIENT_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 sameSSL_KEYSTORE_PASSWORD
value as the one which was generated in/shared/custom/env/server.env
. - 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:
To mount these files,volumes: - ./config/tls/key.p12:/shared/custom/tls/key.p12:Z - ./config/tls/trusts.p12:/shared/custom/tls/trusts.p12:Z
dba-user (id=50001)
must have access to these files:
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, allchown 50001:0 *.p12 chmod 400 *.p12
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. - 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, IBM Workplace, and, when you are running the Workflow Process Service Authoring environment, the IBM Business Automation Studio.
3. Running your environment
- If your operating system is Linux and uses Docker as the container engine, make sure the
container has read and write permissions in the folder where you want to run
docker-compose
. Because the container user ID is50001
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
- To get the Docker image, follow one of these sets of steps.
- Connect to the Docker repository where the Docker image is.
- Log in to MyIBM Container Software Library with the IBMid and password that is associated with the entitled software.
- 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.
- Use the command
docker login cp.icr.io
and log in to the entitled registry with your entitlement key.
- Download the Workflow Process Service package (.tgz file)
from IBM Passport Advantage.
- In Passport Advantage, search for "IBM Cloud Pak for Business Automation 21.0.2 Workflow Process Service Multiplatform English (G01HFEN)" and download "CP4BA_21.0.2-wps.tgz". See IBM Cloud Pak for Business Automation 21.0.2 Download Document.
- Extract the archive.
- Load the images by changing directory (cd) to the extracted images folder and running the docker
load command.
docker load -i workflow-ps-authoring_21.0.2.tar.gz docker load -i workflow-ps-server_21.0.2.tar.gz
- (Optional) Push the images to your docker registry. Log in to your docker registry, and push the
docker images into your docker registry using the following
commands:
wheredocker login <server> docker tag workflow-ps-server:21.0.2 <server>/workflow-ps-server:21.0.2 docker tag workflow-ps-authoring:21.0.2 <server>/workflow-ps-authoring:21.0.2 docker push <server>/workflow-ps-server:21.0.2 docker push <server>/workflow-ps-authoring:21.0.2
<server>
is the host of the docker image registry that you want to use to pull the images. For example,myregistry.local:5000
orlocalhost:8080
for a self-hosted registry.Update the image tags in the docker-compose.yml file.
- Connect to the Docker repository where the Docker image is.
- Start your Workflow Process Service environment by
running the command
docker-compose up
in the folder where the docker-compose.yml file is located. - 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.
Process Portal is not deployed in Workflow Process Service.
- To start your environment, run
docker-compose start
. - To stop your environment, run
docker-compose stop
. - To restart your environment, run
docker-compose restart
. - To delete your environment, run
docker-compose down
. This command stops and deletes all running containers as well as the Docker network created bydocker-compose
. The Docker volumes remain so that your data is recovered next time you start the environment. You must calldocker-compose down
between two consecutive calls ofdocker-compose up
. Otherwise, PostgreSQL will fail to start.
4. Verifying your installation
- Go to
https://external_hostname:external_https_port/Workplace
to launch the hiring sample process. - Go to https://external_hostname:external_https_port/oidc/endpoint/ums/registration to verify that OIDC clients are registered successfully.
- To get the access URLs, admin username, and admin password, run the following
command:
Follow the links in the output of the command to access Workplace and Business Automation Studio.docker exec <container_name> /scripts/post-deployment.sh
- To get information about your environment variables, run the following
command:
docker exec <container_name> /scripts/get-env-info.sh
workflow_runtime_data
- This volume contains the data that is persisted across restartsworkflow_runtime_logs
- This volume contains logs, first failure data capture (FFDC) data, and heap dumps generated by the container
docker volume ls
. To retrieve the location of the
volume in your Docker host filesystem, run docker volume inspect
volume_name
. To delete a volume, run docker volume rm
volume_name
.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
docker-compose up
, you might get the following
error:mkdir: cannot create directory '/shared/custom/env': Permission denied
pc exited with code 1
Follow these steps:
- Run
docker volume ls
to check the created volumes, then find the volume whose name containsproduction_workflow_runtime_data
. Check the details of the volume. - The device that is output by
docker volume inspect production_workflow_runtime_data
is resolved to an absolute path ifdocker-compose
is run successfully. If the output device is not an absolute path, you must upgradedocker-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": "./", ... }, ...... }
- The following is an example of
Cannot access Workplace or Business Automation Studio in Chrome
- Click the lock icon to the left of the URL.
- In the box that pops up, click Certificate is not valid.
- Another box pops up showing information about the certificate. Drag the large certificate icon
to a Finder window. A
cer
file is created in the location you drag it to. - Open the Keychain Access app on your Mac.
- Go to the Certificates tab and drag your
cer
file onto the Keychain Access app. - Double-click your Workflow Process Service certificate and expand the Trust section. Under the When using this certificate section, set the value to Always Trust.
- Close the dialog box and use your Mac password to save your settings.
You can customize Workflow Process Service in many ways, including by setting environment variables or Liberty variables. See Customizing Workflow Process Service.
Parent topic: Installing