Overview - Quantum Fabric Single Container Solution

The Quantum Fabric Single Container On-Premises solution offers a quick way to set up Quantum Fabric on your local environment. It leverages the following technology:

  • Docker - To package different components as portable container images (with all the required binaries and libs).
NOTE:
  • For versions V9 ServicePack 5 or later, containers for the Fabric components run on the Red Hat Universal Base Image (UBI).
  • For versions V9 ServicePack 4 or earlier, containers for the Fabric components run on a Debian image.

Salient Features

The Quantum Fabric Single Container Solution provides developers with tools to build applications.

The Quantum Fabric Single Container Solution has the following features:

  1. Deploys Quantum Fabric on a native Docker container.
  2. Supports deployment on Linux platform.

Prerequisites

  • For V9SP5 (or earlier), install Docker Engine version 19.03.13, and Docker Compose version 1.27.4.
    For V9SP6 (or later), install Docker Engine version 20.10.17, and Docker Compose version 2.6.0.
    NOTE:
    • For Linux, you must install Docker Engine and Docker Compose separately.
  • On Linux machines, use the default Bash prompt to run the install-fabric.sh script.
  • Install Java 11.
  • Install an external Database. (The supported types are mentioned here.)
NOTE:
  • Intel VT and related settings must be enabled in system BIOS.
  • To execute the installation scripts, you must use Bash version 4 or later.
  • To avoid an unknown host exception, make sure that the IP address is configured with the hostname. To do so, follow the steps that are mentioned in the FAQs section.

Software Requirements

Recommended Operating Systems

Temenos recommends using the following operating systems to install Quantum Fabric Single Container Solution:

Operating System Recommended Version
Linux CentOS 7.2

 

Supported Application Servers

Quantum Fabric Single Container Solution only supports the Tomcat Application Server.

Docker images for Quantum Fabric are built using Tomcat and JDK as the base image.

  • V9SP2 (or earlier) is built using Tomcat 8.5.35-jre11
  • V9SP2FP1 to V9SP5 is built using Tomcat 9.0.33-jdk11
  • V9SP6 (or later) is built using Tomcat 9.0.62-jdk11

Supported Databases

Quantum Fabric Single Container Solution supports the following database servers:

Database Type Version Supported
Postgres 14.4
MySQL 5.6, 5.7, 8.0.26
Microsoft SQL Server 2016, 2017
NOTE:
  • MySQL 8 and MySQL 8 Cluster are supported from certain versions of Quantum Fabric. For more information, refer to the Quantum Fabric - Supported OS, Application Servers, and Databases Guide.
  • Multi-node setups for Quantum Fabric are not supported with Postgres.
  • You must have an existing external database. Databases do not come bundled with the Installer.

Hardware Requirements

  • CPU: Dual-core processor
  • Memory: A minimum RAM of 8 GB is required. Temenos recommends using a system with 16 GB RAM.

Architecture

For flyway migrations, a container with database image (kony-fabric-db) is created. The database image is terminated after all the migrations are completed.

After the migrations are completed, the second container will run the Quantum Fabric Docker single image(kony-fabric-all). This container keeps running in the background for as long as the Quantum Fabric setup is required.

Following are the two containers present in the Quantum Fabric Single Container Solution:

  • Quantum Fabric
  • Database (exists on completion of the Database scripts execution)

The following is the list of Docker images used in the Quantum Fabric Single Container Solution:

  • Fabric (Contains mfconsole.war,   workspace.war, accounts.war, apiportal.war, authService.war, admin.war, services.war, middleware.war, apps.war, and kpns.war)
  • Database (Contains database migration scripts)

Quantum Fabric images will no longer be available to the public. Please ensure to download the tar files and extract the images. For further information, refer to Extracting Images from tar files and pushing into private registry.

Quantum Fabric Single Container Solution downloadable bundle contains the following directories and files.

  • install-fabric.sh - Installation script
  • install-actions.sh - Installation actions script
  • templates - Directory that contains the config template files
  • config.properties - Properties file to pass the inputs to install-fabric.sh instead of giving inputs in shell prompts.
  • lib - Folder that contains the fabric-utils.jar and EncryptionUtility.jar files.

Installation Types

  • Command Line or GUI Installation - Quantum Fabric Single Container Solution can be installed using the bundled install shell script, which will prompt the user for the required values.
  • Silent Installation - The installation script also supports silent installation if the config.properties file is passed as an argument (for example, /path/install-fabric.sh config.properties). Using this, you can have additional ability to pass custom Tomcat JAVA_OPTS, and time-zone settings as well.

Configuration

The following parameters must be provided by the user during Installation:

  1. INSTALL_ENV_NAME - The install environment name can be anything, for example, dev, qa, prod, or eastusprod.

    2. NOTE: The Install Environment Name must not contain numbers.

  2. FABRIC_BUILD_VERSION - The build version of Fabric that you want to install. While upgrading, this specifies the build version to which you want to upgrade.

    NOTE: If you build images by using the PreImage kit, ensure that you tag the Docker images in the config.properties file. For more information, refer to PreImage Kit for Quantum Fabric Containers.

  3. FABRIC_DATABASE_BUILD_VERSION - The build version of the database that you want to use with the Fabric installation.
  4. FABRIC_BUILD_TYPE - The type of Fabric environment that must be created. For production environments, the value must be PRODUCTION. For dev, QA, or other non-production environments, the value must be NON-PRODUCTION.
  5. Application Server Details:
    • SERVER_DOMAIN_NAME: The Domain Name for Quantum Fabric.

      NOTE: Domain name must not be a dynamic IP address or 'localhost'. Although, the domain name can be a static IP address.

    • SERVER_PORT - The Port Number for Quantum Fabric.

      NOTE: Ensure that the specified port is not being used by another service.

    • COM_PROTOCOL: The communication protocol that is used for Quantum Fabric. This value can be either http or https.
    • KEYSTORE_FILE : The path to the existing Keystore file. The path should point to a valid JKS file. This value can be empty if the communication protocol is HTTP.
    • KEYSTORE_FILE_PASS: Password for the Keystore (JKS) file. This value can be empty if the communication protocol is HTTP.
    • KEYSTORE_FILE_PASS_SECRET_KEY: The secret key for the Keystore password. This value is required if the Keystore password is encrypted.
  6. Database Details
    • DB_TYPE - The Database type that is used to host Quantum Fabric. The possible values are:
      • For MySQL DB server: mysql
      • For Azure MSSQL or SQL Server: sqlserver
      • For Oracle DB server: oracle
    • DB_HOST - The Database Server hostname that is used to connect to the Database Server.
    • DB_PORT– The Port Number that is used to connect to the Database Server. This can be empty for cloud manage service.
    • DB_USER - The Database Username that is used to connect to the Database Server.
    • DB_PASS - The Database Password that is used to connect to the Database Server.
    • DB_PASS_SECRET_KEY - This is the decryption key for the database password, which is required only if you are using an encrypted password.

      • IMPORTANT: If you are using an encrypted password, use the values that you receive from the encryption utility. For more information, refer to Encrypting the Database Password.

    • DB_PREFIX – This is the Database server prefix for Quantum Fabric Schemas/Databases.
    • DB_SUFFIX – This is the Database server suffix for Quantum Fabric Schemas/Databases.
      • NOTE:
      • Database Prefix and Suffix are optional inputs.
      • In case of upgrade, ensure that the values of the Database Prefix and Suffix that you provide are the same as you had provided during the initial installation.
    • If DB_TYPE is set as oracle, the following String values must be provided:
      • DB_DATA_TS: Database Data tablespace name.
      • DB_INDEX_TS: Database Index tablespace name.
      • DB_LOB_TS: Database LOB tablespace name.
      • DB_SERVICE: Database service name.
    • USE_EXISTING_DB: If you want to use an existing database from a previous Quantum Fabric instance, set this property to Y. Otherwise, set the property to N.

      If you want to use an existing database, you must provide the location of the previously installed artifacts (the location should contain the upgrade.properties file).

      For example: PREVIOUS_INSTALL_LOCATION = /C/kony-fabric-containers-onprem/kubernetes.

  7. Account Registration Details (not applicable for upgrade):
    • OWNER_REGISTRATION_REQUIRED - If owner registration is required, set this property to Y. Otherwise, set the property to N.
    • OWNER_USER_ID – E-mail ID used for Quantum Fabric Registration.
    • OWNER_PASSWORD – Password used for Quantum Fabric Registration.
    • OWNER_FIRST_NAME – First Name used for Quantum Fabric Registration.
    • OWNER_LAST_NAME – Last Name used for Quantum Fabric Registration.
    • OWNER_ENV_NAME – The Quantum Fabric Environment to publish generated applications.
  8. TIME_ZONE - The Time Zone of the Database used for Quantum Fabric installation.

    NOTE: The Time Zone is an optional value. If you do not provide any Time Zone, it is set to Etc/UTC.

  9. CUSTOM_JAVA_OPTS (applicable for Tomcat application servers) - If you want to add custom Java options for the Tomcat server, add them to this property as a string.

Installation

Run the Quantum Fabric Single Container install script to generate and deploy Quantum Fabric containers.

Steps to Install Quantum Fabric Single Container Solution on On-Premises:

  1. Download the kony-fabric-containers-onprem_<version>_GA.zip from downloads and extract it. The file structure will be as shown below:

    config.properties install-fabric.sh* install-actions.sh* lib/ templates/ fabric/ flyway/

  2. Run the install-fabric.sh file.

    3. NOTE: You must provide execute permissions to run the install-fabric.sh and install-actions.sh files on Linux and macOS.

  3. Enter the Install Environment Name and Domain Name.

    4. NOTE: Domain name cannot be a dynamic IP address or 'localhost'. Although, the domain name can be a static IP address.

  4. For the Database details:
    • In case of new Install, provide the following details.

    • In case you are upgrading using an existing database, you must additionally provide the Previous install artifact directory which is the location of your existing Quantum Fabric instance.
    5. NOTE:
    • Ensure that the database details you provide point to an existing database instance.
    • In case of upgrade, ensure that the database points to the existing instance of the database running Quantum Fabric.
    • Database Hostname cannot be localhost.
    • If the Database Prefix or Suffix contain numeric characters, enclose the values in single quotes (' ').
    • In case of upgrade, ensure that the values of the Database Prefix and Suffix that you provide are the same as you had provided during the initial installation.
  5. Enter the Administration Account Configuration details as shown:

    NOTE: This step is not applicable for upgrades. You can use the credentials that you used to create the initial account.

    NOTE: The Password must contain at least 8 characters, at most 20 characters and must include at least one uppercase letter, one lowercase letter, one digit and one special character.

  6. Enter the Time Zone of your Database as shown:

    NOTE: The Time Zone is an optional value. If you do not provide any Time Zone, it is set to Etc/UTC.

    7. Once all the input parameters are given, the installation procedure starts.

    NOTE: Auto Registration will not occur during upgrade.

    After successful completion of execution, the Quantum Fabric URLs are displayed on the screen.

Limitations

Quantum Fabric Single Container Solution has the following limitations:

  • Support for SPA / Desktop Web is only available for zipped SPA apps, but not for WARs.
  • Log Analytics is currently not supported.

FAQs and Troubleshooting

  • Why does the Integration pod keep restarting after deployment using the container images?

    The log trace for this issue is similar to the following example:

    	at org.springframework.web.servlet.FrameworkServlet.processRequest(FrameworkServlet.j
	... 91 more
Caused by: java.net.UnknownHostException: tiles.apache.org
	at java.net.AbstractPlainSocketImpl.connect(AbstractPlainSocketImpl.java:220) ~[?.?]
	at java.net.Socket.connect(Socket.java:609) ~[?.?]
	at java.net.Socket.connect(Socket.java:558) ~[?.?]

    This issue is caused when the integration service tries to get the .dtd file from tiles.apache.org and cannot resolve the domain name for the IP address because Quantum Fabric was deployed over a private network with a single point of proxy with access to the internet.

    To fix this issue, you need to add the proxy setting to the Tomcat Java service that is running on the container. To add the proxy setting, follow this step:

    1. For the INTEGRATION_CUSTOM_JAVA_OPTS variable, add the following -D parameter:
      

-Dhttp.proxyHost=<IP/DOMAIN NAME OF PROXY> -Dhttp.proxyPort=<PORT>
  • How should I restart a container that has been killed?

    To restart a container you must do the following:

    • Go to Downloads > QuantumFabricSingleContainer-9.x.x.x-GA/fabric/ folder.
    • Run the command: docker-compose up -d.
  • How to configure the IP address as the hostname to avoid an unknown host exception?
    1. Update the hostname and IP in the hosts file.
      • For Linux: “/etc/hosts”
      • Once the file is updated with <IP> SPACE <HOSTNAME>, save and close the file.

        • NOTE: In case you still face an issue with the hostname resolution, you must flush the DNS cache.

    2. Update docker-compose.yml file under Downloads/QuantumFabricSingleContainer-9.x.x.x-GA/fabric/
      • Add a section under restart key in the following order:

        • extra_hosts:
        - "<HOSTNAME>:<IP>"

    Once updated, the file will look like the following image:

Extracting Logs from your Application

To perform any actions related to the logs of your application, you need the names of the containers in the application.

The Container names are:

  • Container name for Fabric: fabric_tomcat_1
  • Container name for Flyway: flyway_flyway_1

If you want to extract logs from a container, execute the following command from your terminal:

  • docker logs -f <container_name>

If you want to teletype (tty) into the container, execute the following command from your terminal:

  • For Linux: docker exec -it <container_name> bash

    • NOTE: A database container terminated after the flyway migrations are complete. As a result, you cannot tty into the database container post installation.

If you want to copy logs (for example: Component logs) from the Fabric container to your local machine, execute the following command from your terminal:

  • docker cp <container_name>:<location_in_container> <location_in_machine>

For example: To copy authService logs, execute the following command from your terminal:

docker cp fabric_tomcat_1:/usr/local/logs/authService.log /d/Fabric/logs

NOTE: Component logs can be found at /usr/local/logs inside the container.

Configuring Visualizer to connect to Quantum Fabric

For details on configuring Visualizer to connect to Quantum Fabric, refer to Connect to Quantum Fabric in the Visualizer User Guide.