TDM Installation and Initial Configuration

This document describes the installation guidelines and the initial configuration activities requires for a new TDM installation or an upgrade of a TDM 7.x version to the current version.

TDM Installation - Prerequisites

The following components must be installed as a prerequisite:

• Fabric Server - Fabric 6.5.9 and above for TDM 7.5.2
• PostgreSQL DB - the TDM DB tables are created on a PostgreSQL DB. Note that you can either use a PostgreSQL v9.6 or v13 versions.

Click here to open the TDM 7.5.2 Docker Installation document.

TDM Package Content

The TDM package added the TDM GUI functionality to Fabric. The TDM package creates the following sub directories:

• apps/nodejs:
  • This is the Node.js component. The TDM GUI works with 10.20.1 Node.js version.
• apps/pgsql-9.6:
  • This directory is needed to enable running the TDM scripts to create the TDM DB on the pre-installed PostgreSQL DB.
• webserver/static/TDM:
  • This directory contain the code of the TDM GUI application.
• TDMGUI:
  • Contains the scripts to create the TDM DB and the HTML of the TDM API DOC.

When opening the TDM package, the package also updates the following:

• Updates the .bash_profile file:
  • Adds the $K2_HOME/apps/pgsql-9.6/bin/ and $K2_HOME/apps/nodejs/bin to the PATH variable.
  • Adds $K2_HOME/apps/pgsql-9.6/lib/ to the LD_LIBRARY_PATH variable.
• Updates fabric/staticWeb/apps.json:
  • Add the TDM to Fabric Web Framework applications.
  • Click for more information about adding applications to Fabric Web Framework.

Installation guidelines for TDM Package on the Fabric Server

You can choose to install TDM natively onto an exist Fabric linux instance and then manually install the TDM package, or you can use the a Docker instance which include the TDM package pre-installe

To install a TDM package on a Fabric server do the following:

• Download the TDM package from the download page. Copy it under the $K2_HOME directory and untar it using the following command:

  tar -zxvf <TDM GUI tar file>

Example:

tar -zxvf tdmui7.5.2_3.tar.gz

Run the following command to avoid an override of the apps.json file:

  tar -zxvf <TDM GUI tar file> --exclude='fabric/staticWeb/apps.json'

• Restart the Fabric node.

• Notes:

  • It is possible to install the TDM application on several Fabric nodes of Fabric cluster, but all of them must work with the same TDM DB.
  • All Fabric nodes must work with the same Redis to have an alignment of the sequence and masking values, generated by the TDM tasks.
  • The TDM and Redis interfaces are defined in Fabric project.

Click here for more information about Fabric and TDM installation.

Redis

The Redis must run in one of the Fabric nodes. All Fabric nodes must work with the same Redis.

Start Redis on One of the Fabric Nodes

• Open for edit the redis.conf file and verify that the bind parameter is commented to enable accessing the redis outsite the Fabric node.
• Go to $K2_HOME/apps/redis/src and run:

cd  $K2_HOME/apps/redis/src
nohup ./redis-server $K2_HOME/apps/redis/redis.conf &
cd  $K2_HOME/

Adding a Password to Redis (Optional)

• It is possible to set a password on Redis. Do the following steps to add a password to Redis:

• Run the following commands on the Fabric node:

  ./redis-cli
  CONFIG SET requirepass <password>
  AUTH <password>

• The IP address and the Redis password must also be populated in the Redis interface in Fabric project.

Update the TDM APIDOC (Optional)

The TDM APIDOC html file is located on the TDM node under $K2_HOME/webserver/static/TDM/apidoc directory.

The TDM APIDOC describes all the Web-Services in the Fabric project including the TDM Web-Services imported from the TDM Library.

Following steps should be following if a new APIDOC should be generated to include project custom APIs:

1. Import from the updated TDM library the following objects:

   • TDM_APIDOC_JSON interface (local file interface)- this interface contains the location of the TDM APIDOC Json file.
   • buildTdmApiJSON Broadway flow.

2. Edit the TDM_APIDOC_JSON interface or define the TDM_APIDOC directory under C:\k2view\ local directory.

3. Deploy Fabric project's Web-Services to the local debug server.

4. Run buildTdmApiJSON Broadway flow to create a JSON under the local directory of TDM_APIDOC_JSON interface. Populate the current TDM version in the TDM Version input parameter. For example, TDM 7.5.1. This version is added to the generated APIDOC.

5. Open the Swagger editor using the following URL: https://editor.swagger.io/.

6. In the Swagger Editor:

   • Click File > Import File and select the TDM_APIDOC.json generated by the Broadway flow.
   • Click Generate Client > html2 to download a zip file with the HTML file to your working station.

7. Extract the zip file and copy the generated HTML file under $K2_HOME/webserver/static/TDM/apidoc directory of the Fabric node where TDM is installed.

8. Open the TDM GUI and click the API Doc tab. Verify that the API doc is displayed properly.

Create the TDM PostgreSQL DB (in case of new installation)

• Go to $K2_HOME/TDMGUI/createTDMDB directory in Fabric.

• Set the following environment variables:

  export DB=<postgreSQL DB name>
  export PG_USER=<postgreSQL DB user name>
  export PGPASSWORD=<postgreSQL DB pwd>
  export PG_HOST=<postgreSQL DB host>
  export PG_PORT=<postgreSQL DB port>

• Add execution permissions to createk2TDMDB.sh.

• Run createk2TDMDB.sh script.

• Note that the D_K2V_PG13_TDM7.5.1.tar.gz PG docker image already contains the TDM 7.5.1 DB.

Upgrade the TDM PostgreSQL DB (if not a new installation)

• Go to $K2_HOME/TDMGUI/createTDMDB/updateTDMDB directory in Fabric.

• Set the following environment variables:

  export PG_HOST=<postgreSQL DB host>
  export PG_PORT=<postgreSQL DB port>

• Add execution permissions to updatek2TDMDB.sh.

• Run createk2TDMDB.sh script.

Import and Deploy the TDM Library

The TDM back-end layer is implemented by Fabric APIs in the TDM Library. Import the TDM Library into the Fabric project and deploy to Fabric the Web Services and the TDM LU to enable the TDM GUI invoking the TDM APIs.

Note that if you already have a TDM 7.x project, you need to delete the TDM category from the Web Services before importing the TDM Library's Web Services.

Click for more information about the TDM Library.

Create K2masking Keyspace in Cassandra

The k2masking keyspace is needed for a TDM implementation to support masking or sequence handling. The k2masking keyspace is automatically created by the the TDM LU's deploy.flow upon the deployment of the TDM LU to Fabric. Alternatively, you can run the masking-create-cache-table.flow from the library of Broadway examples or run the create_masking_cache_table.sql of the TDM Library to create the K2masking keyspace if needed.

Click for more information about sequence handling.

Add Permission Groups Mapping to the TDM

The TDM GUI application is pre-integrated with Fabric Web Framework. The user logins into the Fabric Web Framework and Fabric authenticates the user. The TDM GUI application gets the user id and the user's Fabric roles from the user's session and identifies the user type (Permission Group) by their Fabric roles.

The mapping of each Fabric role to a TDM Permission Group is done by the Permission Groups Mapping TDM window and is kept in permission_groups_mapping TDM DB table.

After installing the TDM, the admin user must login the TDM GUI, open the Permission Groups Mapping window, and define the Permission Group mapping of each user's group (= Fabric role) to enable the TDM users to work properly on the TDM GUI based on their Permission Groups.