Skip to main content

Katalon On-Premises deployment guide v2.1.6

This document serves as a guide for those who want to install and activate their Katalon On-Premises License Server plan.

About the On-Premises License Server​

Note:

  • Only applicable to users with any On-Premises plan.

  • This service only supports Linux (Debian or CentOS based).

  • Existing On-Premises package users can contact our Sales team at business@katalon.com for data migration.

The Katalon Studio On-Premises License Server allows the installation and activation of Katalon Studio at the client's network location. It is best for users who must work within a restricted network environment.

There are two package plans available:

  • License Server only.

  • License Server with Katalon Platform.

Begin the installation process by these preparing your environment. .

System Requirements​

Requirements
Operating System64-bit Linux (Debian or CentOS based)
CPUMinimum 4 cores
MemoryMinimum 16GiB
Hard DriveMinimum 100GiB available hard disk space

Prerequisites​

Before deploying Katalon Platform On-Premises, you need to satisfy the following prerequisites:

Katalon Platform Server​

  • A physical or virtual server that meets the System Requirements.

  • Docker and Docker Compose are installed on the target server. If Docker and Docker Compose are not available via your Linux server's package manager, please review the instructions for manual installation.

User Managed PostgreSQL Server​

  • CPU: Minimum 2 cores

  • Memory: Minimum 8 GiB

  • A PostgreSQL 14.3.x Database Server to host the platform database instances:

    • k1
    • kit

  • A Postgres 14.3.x Database Server with extension: pg_stat_statements

  • PostgresSQL settings:

    • max_connections >=300
    • shared_buffers >= 2 GiB

Network Config​

To access Katalon Platform On-Premises, you need config to open these ports in firewall/security group. Make sure to open these ports (incoming) in Katalon Platform Server:

  • Port 8000: License Server Port. Open this port to support redirecting HTTP to HTTPS.

  • Port 8080: TestOps Port. Open this port to support redirecting HTTP to HTTPS.

  • Port 443: HTTPS Port.

  • Port 9902 (optional): Proxy admin Port.

SSL Certificate​

To run License Server with Katalon Platform, you need to run with two sub-domains (ex: admin.my-domain.com, testops.my-domain.com) that meet these terms:

  • Two FQDNs/URLs are required, one each for the License service and TestOps service.

  • Both FQDNs/URLs must be resolvable by the host VM.

  • Both FQDNs should be added to the SSL certificate.

  • SSL Certificate internally signed by an internal Certificate Authority (CA) must include a certificate chain.

Install the Katalon Platform On-Premises License Server​

Important:

  • Make sure that your environment meets all of the System Requirements and Prerequisites outlined above.

There are two package plans for the On-Premises License Server:

  • License Server only.

  • License Server with Katalon Platform.

Identify which package plan you are on and ensure that you only use the one applicable to you.

Download the Katalon On-Premises package and configure​

Here's how you can obtain the Katalon On-Premises package and configure it according to your needs.

Start the process by contacting the Katalon Sales team at business@katalon.com and asking for the On-Premises package.
  1. Receive the On-Premises package from the Katalon sales team.
  2. Extract or unzip the .zip package file.
  3. Open a terminal emulator (command line). Input this code: 
    mkdir -p /katalon/
    cp katalon-op.zip /katalon/
    cd /katalon/
    unzip katalon-op.zip
  4. Go back to the unzipped folder (named katalon-op). It should contain these files:
    cd /katalon/katalon-op/
    ls -la
    -rw-r--r--  .env
    -rw-r--r--  docker-compose.yml
    -rw-r--r--  images_2.1.0.tar.gz
    -rw-r--r--  katalon-op.crt
    -rw-r--r--  katalon-op.key
  5. Run the command below to load the Docker image. 
    docker load < images_2.1.0.tar.gz
    docker images
  6. Open and reconfigure the .env file. It should contain the following: 
    ### Katalon-OP env

    DB_HOST=<database_hostname>
    DB_PORT=5432
    DB_USERNAME=postgres
    DB_PASSWORD=<database_password>

    # License Server configs
    ADMIN_EMAIL=<email>
    ADMIN_PASSWORD=<password>
    LICENSE_SERVER_URL=https://admin.kata-op.com

    # TestOps configs (ignored without testops profile)
    TESTOPS_FILE_STORAGE_PATH=/opt/testops-data
    TESTOPS_SERVER_URL=https://testops.kata-op.com

    # HTTPS config
    HTTPS_PORT=443
    CERT_PATH=./katalon-op.crt
    KEY_PATH=./katalon-op.key
    KEY_PASSPHRASE=
    Note:

    • Your password must be a minimum of 8 characters, contain at least 1 upper case, 1 lower case, 1 special character, and 1 number, and must not start or end with a space.

  7. Make sure you create a folder for TESTOPS_FILE_STORAGE_PATH. For example, if your preferred configuration is TESTOPS_FILE_STORAGE_PATH=/opt/testops_data, then create folder "/opt/testops_data".
    Run the code below to do so. 
    mkdir /opt/testops_data
    chmod 755 /opt/testops_data
  8. Make sure you have two PostgreSQL databases with these names: k1, kit.
  9. Copy your SSL cert and key to the Katalon On-Premises folder.
    Note:

    • If you are running the License Server with Katalon Platform, then you need to run with two sub-domains (ex: admin.my-domain.com, testops.my-domain.com) and Wildcard SSL.

    Run the code below to copy your SSL cert:
    cp my-domain.crt /katalon/katalon-op/my-domain.crt
    cp my-domain.key /katalon/katalon-op/my-domain.key
  10. Update the .env file with your information.
    1. Replace admin.kata-op.com and testops.kata-op.com with your domain.
      For example:

      DB_HOST=10.10.20.5

      DB_PASSWORD=adminpasswdsql@!!!

      LICENSE_SERVER_URL=https://admin.my-domain.com

      TESTOPS_SERVER_URL=https://testops.my-domain.com

      TESTOPS_FILE_STORAGE_PATH=/opt/testops_data

      ADMIN_EMAIL=admin@katalon-op.local

      ADMIN_PASSWORD=adminpasswd@!!!

      CERT_PATH=./my-domain.crt

      KEY_PATH=./my-domain.key

  11. Run the corresponding command below to start the application. Ensure to use the one that aligns with your plan.
    1. Start Katalon On-Premises, License Server only:
      cd /katalon/katalon-op/
      docker-compose up -d
    2. Start Katalon On-Premises, License Server with Katalon Platform:
      cd /katalon/katalon-op/
      docker-compose --profile testops up -d
After these steps, activate your license.

Activate the On-Premises license​

In order to begin using your Katalon On-Premises license, you must activate it by following the steps below.
  1. Access the admin homepage on the browser. For example, if your LICENSE_SERVER_URL is https://admin.my-domain.com, then enter the URL: https://admin.my-domain.com/.
    1. Wait for Init DB to complete. It takes around 3 to 5 minutes.
    2. The screen automatically redirects to https://admin.my-domain.com/katone/activate-license.
  2. Get your Machine ID to generate your License Key.
    Note:

    • Contact our Sales team at business@katalon.com to get your License Key at this step. Once you have "License Key" based on your package plan, continue to the next steps to active Katalon Platform.

  3. Click Choose File then open your License Key file.
  4. Click Activate.The On-Premises license activation screen
  5. Log in with your username and password. Make sure to use the same credentials in the .env file configured previously. Katalon On-Premises' sign-in screen
After signing in, you are redirected to the homepage. This confirms that you have activated your license successfully.Homepage

Access the Katalon Platform​

To access the Katalon Platform on a browser, you need to manually enter a URL.
Type the name of your TESTOPS_SERVER_URL in your browser.
  1. For example, if your TESTOPS_SERVER_URL is https://testops.my-domain.com, then enter the URL: https://testops.my-domain.com.
This will bring you to the homepage of the On-Premises Katalon Platform.

Stop Katalon On-Premises​

Warning:

  • Running these commands will stop and remove all Docker containers in your server. It will not remove any data in the folder TESTOPS_FILE_STORAGE_PATH and your database.

Ensure to use the command appropriate for your package plan.
  1. To stop Katalon On-Premises License Server only, run the following command:
    cd /katalon/katalon-op/
    docker-compose down
  2. To stop Katalon On-Premises License Server with Katalon Platform, run the following command: 
    cd /katalon/katalon-op/
    docker-compose --profile testops down
Running either command successfully will stop Katalon's On-Premises from running.

Troubleshooting and support for Katalon On-Premises​

If you are having trouble with the On-Premises plan, contact Katalon.

You can contact Katalon directly at business@katalon.com or through your Katalon Partner for any installation or configuration issues you encounter. Our team will work with you directly to resolve any issues.

In order to provide the highest level of customer support, the support team may request certain commands to be executed in order to generate telemetry, utilization, and log data. This will be worked on with you directly.