1.     Introduction

With 30 April 2023 almost upon us and the end of free access to the Mirantis Runtime Engine, those who would like to deploy Planning Analytics Workspace (PAW) on Windows or have done so and require support updates will need to purchase a subscription.

An alternative to Windows is to run Planning Analytics Workspace on Red Hat Enterprise Linux (RHEL). RHEL also requires a support subscription for the operating system and updates but pricing may be more favourable. RHEL uses Podman which can be pulled from the RHEL repositories.

This article takes you through the installation of PAW on RHEL step-by-step. Very little Linux knowledge is required and all the commands should be available in the steps below to easily guide you through your first installation.

At a high-level, these are the steps we will follow:

·         Install and configure RHEL

·         Install and configure Podman

·         Install and configure PAW

·         Log in and test PAW

See this announcement from IBM for further details on the Mirantis Runtime Container:

https://www.ibm.com/support/pages/node/6856989?myns=swgother&mynp=OCSSCTEW&mync=E&cm_sp=swgother-_-OCSSCTEW-_-E

https://community.ibm.com/community/user/businessanalytics/blogs/leo-comunale1/2023/02/28/faq-change-in-mirantis-runtime-engine-formerly-doc?CommunityKey=8fde0600-e22b-4178-acf5-bf4eda43146b

2.     Prerequisites and Assumptions

2.1.     TM1 database

I will assume you already have at least one TM1 database running and configured for PAW to use as the default instance for login authentication. Also, it is assumed that you have added an entry into the TM1s.cfg for the HTTP Port Number that PAW requires for SSL communication with the model e.g.

HTTPPortNumber=32768

UseSSL=T

2.2.     Telnet / SSH client

I will be using MobaXterm to SSH to my server - https://mobaxterm.mobatek.net/ 

You could use any other SSH client e.g. Putty to connect too.

For any commands issued, I am assuming that I am not logged in as root but have an account to allow me to run commands as root through sudo.

For editing files, I typically use VI but you can use Nano which may be easier for those without VI experience.

3.     Install and Configure RHEL 8.5

3.1.     Register Developer Account and Download RHEL

Have your RHEL subscription details available or sign up with a trial or developer account depending on your circumstances:

https://developers.redhat.com/content-gateway/link/3871363

Download the relevant install from:

https://developers.redhat.com/products/rhel/download#assembly-field-downloads-page-content-61451

I have the RHEL 8.5 DVD ISO and have already installed my base RHEL OS from that.

3.2.     Install RHEL

Install RHEL to your server/VM.  My VM has 127GB disk, 16GB RAM. This should be sufficient for a development environment. Follow the installation prompts and after restarting, accept licensing etc. then RHEL should reboot.

After reboot I enabled my wired connection and updated my network settings, then set my IP address to static on 192.168.0.206 and to automatically connect.

Log in on the X Windows System then go to

Do something similar on your server based on your network and its IP range. Keep a note of the IP address for later.

As I am going to be using my own account with sudo, I will need to add my account to the sudoers. You will need to edit this file as root before you can sudo. Open the terminal window or connect using your telnet/SSH client.

su –

vi /etc/sudoers

or

nano /etc/sudoers

Scroll down to the section with root (or %wheel) and add in an entry for your user or group as applicable. I am adding my account below root to allow my user to sudo e.g.

<username> ALL=(ALL) ALL

To insert into VI, you need to press lower-case i then type or paste. Once you have entered text, press escape to come out of edit mode.

Save and exit – file may be read-only so use the override per below to save:

:wq!

In VI, the above forces a save then quits.

Some other useful keys are below:

i - insert text before the cursor

a - append text after the cursor

A - append text at the end of the current line

o - open a new line below the current line and insert text

O - open a new line above the current line and insert text

x - delete the character under the cursor

dd - delete the current line

yy - yank (copy) the current line

p - paste the last yanked (copied) text

:w - write (save) the file

:q - quit vi

:wq - write (save) and quit vi

ESC – exit entry mode

/<string> - Find a string in the file

More commands can be found in through this link:

https://www.cse.scu.edu/~yfang/coen11/vi-CheatSheet.pdf

4.     Install and Configure Podman

4.1.     Create your Podman and PAW directory structure

I like to create a directory off the root called paw and then have my current version as a sub-directory e.g. paw284

I also configure Podman to write the necessary files here as I have had instances where the filesystem where the default containers are stored is too small to house them or even extract the PAW images. In some cases IT provide an encrypted filesystem where all files need to reside so I typically create the containers directory and pawtmp directory here too.

/paw

├── containers

├── paw284

└── pawtmp

Switch to superuser so that you can create directories and issue other commands:

su -

cd /

sudo mkdir paw

sudo mkdir paw/pawtmp

sudo mkdir paw/paw284

sudo mkdir paw/containers

sudo mkdir paw/containers/storage

To view the structure you created, you can issue the tree command

tree /paw

4.2.     Install and Configure Podman

Update all your repositories. First su to root if not already there.

su -

yum makecache

Once cache has been created, update from it. This can take a few minutes depending on the number of updates.

yum update

Once updated, clean the cache

yum clean all

Install Podman ahead of PAW to be able to configure or change any required settings.

yum install -y podman

You should see something like the below if any updates are needed but previous step should have done this already:

Updating Subscription Management repositories.

…

Upgraded:

  podman-2:4.2.0-11.el9_1.x86_64                    podman-catatonit-2:4.2.0-11.el9_1.x86_64

Create or edit the Podman configuration files:

vi /etc/containers/containers.conf

Add the following content or update as necessary

[engine]

env=["TMPDIR=/paw/pawtmp"]

Update the storage.conf to set the new container storage location

vi /etc/containers/storage.conf

Locate and update the graphroot directory:

graphroot="/paw/containers/storage"

These two changes are particularly useful when you have additional filesystems that you want to use for your containers or possibly a very small tmp filesystem that fills when extracting the containers.

Per the notes in the storage.conf file, run these two commands to update Podman with the settings that have changed and relink to the new container path if SELinux is enabled:

sudo semanage fcontext -a -e /var/lib/containers/storage /paw/containers/storage

sudo restorecon -R -v /paw/containers/storage

Enable the Podman service and start it.

systemctl enable --now podman.socket

You should see a message confirming that a symlink has been created:

Created symlink /etc/systemd/system/sockets.target.wants/podman.socket → /usr/lib/systemd/system/podman.socket.

Test that Podman is installed and running

podman run hello-world

You should see the following returned indicating the Podman is configured and running:

Resolved "hello-world" as an alias (/etc/containers/registries.conf.d/000-shortnames.conf)

Trying to pull quay.io/podman/hello:latest...

Getting image source signatures

Copying blob 51c95f5eac86 done

Copying config aa20ddcead done

Writing manifest to image destination

Storing signatures

!... Hello Podman World ...!

         .--"--.

       / -     - \

      / (O)   (O) \

   ~~~| -=(,Y,)=- |

    .---. /`  \   |~~

 ~/  o  o \~~~~.----. ~~

  | =(X)= |~  / (O (O) \

   ~~~~~~~  ~| =(Y_)=-  |

  ~~~~    ~~~|   U      |~~

Project:   https://github.com/containers/podman

Website:   https://podman.io

Documents: https://docs.podman.io

Twitter:   @Podman_io

Also, if you look in the /paw/containers/storage directory, you should now see some files and directories that have been created:

ls -l /paw/containers/storage/

total 12

-rw-r--r--. 1 root root    8 Mar 12 14:18 defaultNetworkBackend

drwx------. 2 root root   27 Mar 12 14:18 libpod

drwx------. 2 root root    6 Mar 12 14:18 mounts

drwx------. 5 root root 4096 Mar 12 14:18 overlay

drwx------. 3 root root  124 Mar 12 14:18 overlay-containers

drwx------. 3 root root  116 Mar 12 14:18 overlay-images

drwx------. 2 root root  129 Mar 12 14:18 overlay-layers

-rw-r--r--. 1 root root   64 Mar 12 14:18 storage.lock

drwx------. 2 root root    6 Mar 12 14:18 tmp

-rw-r--r--. 1 root root    0 Mar 12 14:18 userns.lock

You can exit root by typing in exit and returning to your user account.

4.3.     Configure Directory Permissions

Depending on how you want to control access to the various directories, you may want to consider adding a group that has access to the PAW directories and is allowed to managed files, logs etc.

To keep things simple for now, I am going to leave ownership on root only and permissions to /paw as:

drwxr-xr-x.   5 root root   52 Mar 19 08:20 paw

5.     Planning Analytics Workspace Installation

5.1.     Download PAW from Fix Central

If you do not already have a copy of the latest version of Planning Analytics Workspace, follow the link below to download from Fix Central:

https://www.ibm.com/support/fixcentral/swg/selectFixes?parent=Analytics%20Solutions&product=ibm/Information+Management/IBM+Planning+Analytics+Local&release=2.0&platform=Windows+64-bit,+x86&function=textSearch&text=Planning+Analytics+Workspace

The file you are looking for should be named similarly to:

ipa_workspace_local_2.0.84.922.zip

There is also a ipa_workspace_local_dist_2.0.84.922.zip – Distributed is for deployment to Red Hat OpenShift Container platforms. See the following link for additional details as I will not be covering that type of installation here:

https://www.ibm.com/docs/en/planning-analytics/2.0.0?topic=configuration-planning-analytics-workspace-distributed

5.2.     Copy the Install Files to the Server

For the PAW installation, I am assuming you are running as user account not root or superuser. All commands will thus use sudo to execute them.

If you are running as root or superuser, you can drop the sudo directive from each command.

Once downloaded, copy over the installation archive to your PAW server’s /paw/paw284 folder. If you are using MobaXterm, you can simply drag the file from your file explorer to your home directory and move it into the PAW directory.

cd /paw/paw284

sudo mv /home/george/ipa_workspace_local_2.0.84.922.zip .

Change to the PAW folder if you skipped the step above and unzip the archive to extract the files and directories for PAW:

cd /paw/paw284

sudo unzip ipa_workspace_local_2.0.84.922.zip

Archive:  ipa_workspace_local_2.0.84.922.zip

   creating: config/

   creating: config/certs/

  inflating: config/certs/applixca.pem

  inflating: config/certs/ibmtm1.pem

  inflating: config/certs/tm1ca_v2.pem

  inflating: config/README_certs.txt

  inflating: config/pa-workspace.pem

  inflating: config/paw.env.sample

  inflating: config/network.static.yml

  inflating: config/network.yml

  inflating: config/podman-docker.env

  inflating: config/defaults.env

  inflating: config/version.env

   creating: images/

  inflating: images/images.env

  inflating: images/images.tar

…

Once extracted you can confirm that the relevant files and directories have been extracted:

ls -l

total 2298196

drwxr-xr-x.  3 root   root         4096 Feb 25 00:14 config

drwxr-xr-x.  2 root   root           42 Feb 25 00:19 images

-rw-rw-r--.  1 george george 2353322271 Mar 12 14:42 ipa_workspace_local_2.0.84.922.zip

drwxr-xr-x.  2 root   root         4096 Feb 25 00:14 licenses

-rwxr-xr-x.  1 root   root          202 Feb 25 00:14 README.txt

drwxr-xr-x.  2 root   root         4096 Feb 25 00:14 scripts

drwxr-xr-x. 23 root   root         4096 Feb 25 00:14 services

drwxr-xr-x.  2 root   root           62 Feb 25 00:14 software

-rwxr-xr-x.  1 root   root         1208 Feb 25 00:14 Start.bat

-rwxr-xr-x.  1 root   root         2343 Feb 25 00:14 Start.sh

drwxr-xr-x.  2 root   root           68 Feb 25 00:14 swidtag

I typically remove the zip file after extraction as it is no longer required:

sudo rm ipa_workspace_local_2.0.84.922.zip

5.3.     Execute the Installation

The Start.sh script is used to start the installation or the Admin Tool. Before we run the installation we need to export a variable called ADMINTOOL_IP. The IP address exported should not be the address of the server on the network, not the local loopback on 127.0.0.1 as that will not allow you to connect from you browser, only through the browser in the X Window System if installed.

Use the following to find the server IP address bound to the ethernet adapter, eth0:

sudo ifconfig

In my case this is 192.168.0.206 so I will execute the following to set the ADIMNTOOL_IP and make it available in the root environment when the start script is executed.:

sudo -E bash -c 'export ADMINTOOL_IP=192.168.0.206; ./Start.sh'

If you do not specify the ADMINTOOL_IP, you will need to connect to the Admin Tool on a local browser i.e. the X Windows System. You will not be able to connect from another machine.

Specifying a different ADMINTOOL_IP after the installation could cause issues with connecting to the container due to network bindings and the IP address in the container.

5.4.     Configure PAW Environment

Once the Admin Tool has started point your browser to the URL e.g http://192.168.0.206:8888

You will need to accept the license agreement on both tabs.

Update the Configuration tab with the details of your TM1 server.

TM1 Application Server Gateway URI will always return an error as it has been deprecated. I still configure as if it were going to connect with the pmpsvc or TM1Web.

TM1 Login Server URI require the HTTPPortNumber from the TM1s.cfg of the TM1 instance you want to use as the primary instance and will be used to authenticate against. Assuming for purposes of this document that we are using TM1 Authentication Mode. Please use a suitable TM1 database to connect to that has IntegratedSecurityMode=1 or 2 for native or mixed mode.

Click Validate to ensure that the Admin Server and TM1 Login Server are reachable.

If they are not reachable, check your settings, ensure that you have UseSSL=T and the correct HTTPPortNumber

You can also use curl to check if the ports are reachable:

sudo curl -k <server>:5898 --output test.txt

e.g. sudo curl -k 192.168.0.203:5898 --output test.txt

sudo curl -k <server>:<HTTPPortNumber> --output test.txt

e.g. sudo curl -k 192.168.0.203:41001 --output test.txt

Assuming all is valid, you can then click on the Update button to start the PAW containers.

Navigate to the Status tab to monitor progress. Ideally you want to see that containers are in a running state.

Initialization should show as completed and will not be running.

Keep an eye on the CPU % as until these have settled down to very low values, the services are still loading and not ready.

Any containers with a status of exited are not running and likely have some issue. You can click on the Service name then click Logs to retrieve and view the log. Alternatively, you can view the log in the command line using:

sudo podman logs <service>

e.g. sudo podman logs atlas

If you are not sure if the correct name for the service, you can check these using the following:

sudo podman ps

This will also give you some information on each service.

If you want to monitor the containers as they start up or are running, you can use:

sudo podman stats

You should see view per below that is updated every 5 seconds:

Ctrl+C to stop the stats display.

Refer to the following link and table below for Service names and descriptions:

https://www.ibm.com/support/pages/planning-analytics-workspace-services-and-associated-logs

Service	Folder name	Description
Administration	user-admin	User administration service
Authorization	bss	Manages accounts, tenants, users, roles, capabilities
Chat	social	Chat service
Content Delivery	cdn3p	Apache proxy serves up static files to browser clients
Content Store	neo-idviz	PAW Content Store to store books, views, etc
CouchDB	couchdb	CouchDB is a document-centric database used to store user chats
CouchDB Initialization	couchdb_init	Initializes CouchDB
Gateway	pa-gateway	Main Apache gateway into PAW
Glass	glass	Manages components in the PAW UX
Initialization	bss-init	Provides initial configuration of BSS
MongoDB	mongo	MongoDB is a document-oriented database. Assets such as books and views are stored here
Monitor	monitor	PAA Monitor
PA Content Service	pa-content	Layer on top of the Workspace services that provides more efficient or advanced retrieval
PA Proxy	wa-proxy	PAW proxy
Provisioning	neo-provision	PAW Content Store configuration agent
Redis	redis	Redis is an in-memory key/value store used by PAW to persist user settings, favorites and bookmarks
Share Application	share-app	Share UX service
Share Platform	share-platform	Share core service
Share Proxy	share-proxy	Apache proxy in front of paw_share-app and paw_share-platform
TM1 Proxy	tm1proxy	Used by PA for Excel to proxy requests to TM1 OData APIs
Welcome	welcome	Welcome page service
Workspace Application	prism-app	Dashboard service
Workspace Platform	prism-platform	Query engine, modelling support and ancillary services
Workspace Proxy	prism-proxy	Apache proxy in front of paw_prism-app and paw_prism-platform
Workspace UI API	paw-ui-api	Supports embedding PAW UI components in other applications

5.5.     Logging in for the First Time

Point your browser to the IP Address of your server, per what we used in the ADMINTOOL_IP. If all services started correctly and have finished loading you should get a login screen.

Keep in mind that whoever logs in for the first time becomes the PAW administrator. If you are logging in as someone other than admin, you will want to create additional users and assign the necessary Admin privileges.

Once successfully logged in, you should see the home screen:

From here, you can click on the hamburger menu at the top left and navigate to Administration:

You should be able to see the databases on the server, agents and users and groups. At this stage obviously just the one user, you, assigned as an Administrator.

6.     Controlling PAW

6.1.     Starting PAW

https://www.ibm.com/support/pages/how-stop-and-start-planning-analytics-workspace-command-line

Scripts are located in the scripts directory of the PAW installation. In our case: /paw/paw284/scripts

Run the following to start PAW:

sudo ./paw.sh start

If PAW is running and you want to restart the containers, you can issue the following command:

sudo ./paw.sh restart

6.2.     Stopping PAW

To stop the PAW containers you can issue the following command:

sudo ./paw.sh stop

6.3.     Updating PAW Settings

PAW settings are located in the config directory i.e.

/paw/paw284/config

The default settings are configured in the defaults.env file. Any changes to these defaults should be added into the paw.env file which contains the settings we captured into the Administration Tool before starting the services.

For additional details see the Configure Parameters page:

https://www.ibm.com/docs/en/planning-analytics/2.0.0?topic=local-configure-parameters

7.     Future Considerations

Now that PAW is configured and running, read up on making backups of PAW and the configuration in the containers, upgrading to new versions etc.

https://www.ibm.com/docs/en/planning-analytics/2.0.0?topic=local-back-up-restore-planning-analytics-workspace

https://www.ibm.com/docs/en/planning-analytics/2.0.0?topic=local-upgrade-planning-analytics-workspace

You could also look at configuring PAW with your own certificate. Ensure that it is not an encrypted PEM file though. IBM page is a bit thin on detail but will cover this in a future article if there is a need.

https://www.ibm.com/docs/en/planning-analytics/2.0.0?topic=servers-configure-tls-planning-analytics-workspace-local

Additionally, you could look into configuring the Planning Analytics Administration agent and registering a SendGrid account to allow you to configure and send mail from PAW.

https://www.ibm.com/docs/en/planning-analytics/2.0.0?topic=mad-install-configure-planning-analytics-administration-agent-local-only

https://www.ibm.com/docs/en/planning-analytics/2.0.0?topic=icpaaalo-enable-email-notifications

8.     Conclusion

I trust you were able to configure your RHEL server and load and configure PAW accordingly. and then log in.

Assuming all the steps above worked for you, you should be in a position to assess whether or not PAW on RHEL is a suitable and possibly better fit for your organisation. My personal findings indicate that PAW on RHEL is a lot faster than any of the Windows servers I had previously run it on.

As always, if you experience any issues with any of the steps, see mistakes or have a better way of doing things, please leave a comment so that I can correct issues or others can gain insight from your feedback.

9.     Further Troubleshooting

View the Administration Tool log

sudo podman logs admintool

Test if you the Administration Tool is running if your browser is not connecting:

curl -k <server>:8888

e.g. curl -k 192.168.0.203:8888

This should return the content of the page as text if the connection can be made. Firewalls could also be something to check where connections are not possible

Cannot connect to the Administration Tool on the specified IP address.  Restart the Administration Tool as it may be bound to 127.0.0.1

sudo podman restart admintool

Review the link if you get the below error:

Error: can only create exec sessions on running containers: container state improper

https://www.ibm.com/support/pages/node/6957448

Last resorts:

Remove all containers

sudo podman system prune

Remove all networks, containers etc. and go back to a state before you ran ./Start.sh

sudo podman system reset

After each reboot, some Planning Analytics Workspace containers are failing to start

https://www.ibm.com/support/pages/node/1072356?myns=swgimgmt&mynp=OCSSD29G&mync=E&cm_sp=swgimgmt-_-OCSSD29G-_-E

All containers are in "Restarting" state on Linux, and logs are empty

https://www.ibm.com/support/pages/node/6956878?myns=swgother&mynp=OCSSCTEW&mync=E&cm_sp=swgother-_-OCSSCTEW-_-E

Planning Analytics Workspace Services and Associated Logs

https://www.ibm.com/support/pages/planning-analytics-workspace-services-and-associated-logs

#ibmchampions-highlights-home #ibmchampions-highlights