Skip to main content

Katalon On-Premises deployment guide v3.0.0

This guide provides instructions on how to install Katalon On-Premises version 3.0.0, covering both License Server and Katalon Platform options.

About the On-Premises License Server​

Note:

  • The On-Premises License Server only applicable to users with any On-Premises plan.

  • The On-Premises License Server only supports Linux.

  • Existing On-Premises package users can contact our Sales team at business@katalon.com for information regarding Katalon Studio plan upgrades and 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 need to work within a restricted network environment.

There are two package plans available:

  • License Server only.

  • License Server with Katalon Platform.

To install Katalon Platform On-Premises successfully, ensure your Linux host meets the following general requirements.

Prerequisites​

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

Katalon Platform Server​

Supported platforms:

  • 64-bit Linux (x86_64 architecture) distributions:

    • Ubuntu

    • Debian

    • Red Hat Enterprise Linux (RHEL)

Note:

  • Katalon On-Premises has not tested or verified installations on other platforms.

General system requirements:

Operating System64-bit Linux (Debian or CentOS based)
CPUMinimum 4 cores
MemoryMinimum 16 GiB
Hard DriveMinimum 100 GiB available hard disk space
Docker and Docker Compose v2 are installed on Katalon Platform server. If Docker and Docker Compose are not available via your Linux server's package manager, refer to the following instructions for manual installation.

User Managed PostgreSQL Server​

In general, the Katalon On-Premises Platform only supports the PostgreSQL database management system.

  • The recommended version of PostgreSQL is 14.3.x

  • CPU: Minimum 2 cores

  • Memory: Minimum 8 GiB

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

    • k1

    • kit

    • keycloak

  • Enable extension: pg_stat_statements

The following table lists the minimum and recommended values for the configuration parameters:

ParameterMinimum ValueRecommended Value
max_connections200400
shared_buffers2 GiB8 GiB

Network Configuration​

To access Katalon Platform On-Premises, configure to open these ports in firewall/security group. Make sure to open these ports (inbound/outbound) in Katalon Platform Server:

  • 443: HTTPS Port

  • 8000: License Server Port

  • 8080: TestOps Port

  • 8081: Authorizer Port

SSL Certificate​

To run the License Server with Katalon Platform with HTTPS, you need to run with three sub-domains that meet:

  • A domain for License Server (ex: admin.my-domain.com);

  • A domain for TestOps (ex: testops.my-domain.com);

  • A domain for Authorizer (ex: login.my-domain.com); and

  • SSL Certificate for your domain.

Install the Katalon Platform On-Premises License Server​

The following is the complete process of installing and configuring the Katalon Platform On-Premises License Server. Make sure your environment meets all of the system requirements and prerequisites as outlined, see Prerequisites.

You will learn how to:

  • Back up your existing databases.

  • Create and configure the Keycloak database.

  • Download, configure, and deploy the License Server and TestOps.

  • Set up TestOps storage.

  • Configure SSL certificates and update environment variables.

  • Start the services using Docker Compose.

Back up the database​

Warning:

  • This backup step is critical. Ensure all existing databases are backed up before proceeding with the upgrade to avoid potential data loss.

  1. Stop the existing services.
    To stop the Katalon On-Premises version 2.0.x, run the following commands.
    Note:

    • The steps below assume the install directory is /katalon/katalon-2.0.x. If your install directory differs, substitute your own installation path.

    • On a Terminal, navigate to the install directory:
      cd /katalon/katalon-2.0.x/
    • (If using only the License Server) Enter the following command to stop all containers:
      docker compose down
    • (If using both License Server and TestOps) Enter the following command to stop all containers:
      docker compose --profile testops down
  2. Backup PostgreSQL (k1, kit).
    You can back up your PostgreSQL database using any of the following methods:

    • Method 1: Using psql prompt. See PostgreSQL documentation: psql.

      Here's an example of how to back up the k1 and kit databases using the psql prompt:
      pg_dump --file "kit_backup_DATE.sql" --host "<DB_HOST>" --port "<DB_PORT>" --username "<DB_USERNAME>" --format=p --verbose kit
      pg_dump --file "k1_backup_DATE.sql" --host "<DB_HOST>" --port "<DB_PORT>" --username "<DB_USERNAME>" --format=p --verbose k1

    • Method 2: Via AWS console.

      • On your AWS console, navigate to the RDS dashboard.

      • Select your RDS.

      • Select Actions > Take snapshot.

    • Method 3: Using database management tools such as pgAdmin (see pgAdmin documentation), DBeaver (see DBeaver documentation), etc.

Create the Keycloak database​

In Katalon On-Premises version 3.0.0, a new database named keycloak is required in addition to the existing k1 and kit databases.
  1. Access the PostgreSQL server.
    You can access PostgreSQL using one of the following methods:
    • Method 1: Using psql prompt:
      psql -h <DB_HOST> -U <USER_NAME> -p <DB_PORT>
    • Method 2: Via AWS console.

      • On your AWS console, navigate to the RDS dashboard.

      • Select your RDS.

      • Select Actions > Take snapshot.

    • Method 3: Using database management tools such as pgAdmin, DBeaver, etc.

  2. Create the keycloak database.
    Once connected to PostgreSQL, run the following command to create the keycloak database:
    CREATE DATABASE keycloak;
  3. Verify the databases.
    After creating the keycloak database, ensure that all three required databases (k1, kit, and keycloak) exist in PostgreSQL by running the following command:
    \l

    The output should include the three required databases:

    psql (14.12 (Ubuntu 14.12-0ubuntu0.22.04.1))
    SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, bits: 256, compression: off)
    Type "help" for help.

    postgres=# \l
                                  List of databases
       Name    |  Owner   | Encoding | Collate |  Ctype  |   Access privileges   
    -----------+----------+----------+---------+---------+-----------------------
     k1        | postgres | UTF8     | C.UTF-8 | C.UTF-8 | 
     keycloak  | postgres | UTF8     | C.UTF-8 | C.UTF-8 | 
     kit       | postgres | UTF8     | C.UTF-8 | C.UTF-8 | 
     postgres  | postgres | UTF8     | C.UTF-8 | C.UTF-8 | 
     template0 | postgres | UTF8     | C.UTF-8 | C.UTF-8 | =c/postgres          +
               |          |          |         |         | postgres=CTc/postgres
     template1 | postgres | UTF8     | C.UTF-8 | C.UTF-8 | =c/postgres          +
               |          |          |         |         | postgres=CTc/postgres
    (6 rows)

    postgres=#

Download the Katalon On-Premises package and configure​

After creating the Keycloak database, download and configure the Katalon On-Premises package for version 3.0.0.
Note:

  • You will receive the On-Premises package from the Katalon Sales team. If you have not yet received the package, contact the team at business@katalon.com.

  1. Prepare the installation directory.
    1. Open a Terminal.
    2. Enter the following command to create the installation directory: mkdir -p /katalon/katalon-3.0.0/
    3. Enter the following command to copy the downloaded package to the installation directory: cp katalon-op-3.0.0.zip /katalon/katalon-3.0.0/
  2. Verify the package.
    Run the following command to verify if the package was copied successfully:
    ls -al
    You should see an output similar to this:
    drwxr-xr-x 3 root root       4096 Jun  4 03:43 .
    drwxr-xr-x 5 root root       4096 May 30 14:45 ..
    -rw-r--r-- 1 root root 5008436657 Jun  3 09:02 katalon-op-3.0.0.zip
  3. Unzip the package.
    Unzip the package by running the following command:
    unzip katalon-op-3.0.0.zip
    This will create the katalon-op directory:
    drwxr-xr-x 3 root root       4096 Jun  4 03:43 .
    drwxr-xr-x 5 root root       4096 May 30 14:45 ..
    drwxrwxr-x 3 root root       4096 Jun  4 07:56 katalon-op
    -rw-r--r-- 1 root root 5008436657 Jun  3 09:02 katalon-op-3.0.0.zip
  4. Navigate to the unzipped folder.
    Change to the katalon-op directory and list its contents:
    cd katalon-op
    ls -al
    You should see a list of files similar to the example below:
    drwxrwxr-x 3 root root       4096 Jun  4 07:56 .
    drwxr-xr-x 3 root root       4096 Jun  4 03:43 ..
    -rw-rw-r-- 1 root root        960 Jun  4 07:56 .env
    -rw-rw-r-- 1 root root       1090 Jun  3 08:59 Build-Info.txt
    -rw-rw-r-- 1 root root       6105 Jun  3 08:44 docker-compose.yml
    -rw-rw-r-- 1 root root 5033163363 Jun  3 08:59 images_3.0.0.tar.gz
    -rw-rw-r-- 1 root root       1305 Jun  3 08:44 katalon-op.crt
    -rw-rw-r-- 1 root root       1703 Jun  3 08:44 katalon-op.key
    drwxr-xr-x 2 root root       4096 Jun  4 04:32 logs
  5. Load Docker images.
    To load the images for version 3.0.0, run the following command:
    docker load < images_3.0.0.tar.gz
  6. Verify Docker images.
    Run the following command to verify if the Docker images were successfully loaded:
    docker images
    You should see a list of Docker images similar to the example below:
    REPOSITORY                       TAG       IMAGE ID       CREATED        SIZE
    katalon-op/testops               3.0.0     bc8505e7d8dd   3 days ago     422MB
    katalon-op/license-server        3.0.0     5d8fd0ce786e   3 days ago     1.03GB
    katalon-op/keycloak              3.0.0     bae44d368348   3 days ago     449MB
    katalon-op/repo-scanner          3.0.0     52d01a25eaa4   6 days ago     724MB
    katalon-op/organizing-be         3.0.0     fc3d1ddb9185   8 days ago     477MB
    katalon-op/envoy                 3.0.0     5c7ce86459f0   9 days ago     170MB
    katalon-op/kafka                 3.0.0     577b760f3875   9 days ago     551MB
    katalon-op/authorizer            3.0.0     2697d9fc45bd   11 days ago    160MB
    katalon-op/keycloak-config-cli   3.0.0     08ea2d10abfd   13 days ago    275MB
    katalon-op/testops-engine        3.0.0     d06b7736e9f2   4 weeks ago    5.27GB
    katalon-op/redis                 3.0.0     92714677dba2   2 months ago   116MB
    katalon-op/zookeeper             3.0.0     b191a95f8d52   N/A            510MB
  7. Verify image details.
    To ensure the image versions match your Katalon On-Premises plan, open the Build-Info.txt file and compare the IMAGE ID against the Docker image list above with this command:
    cat Build-Info.txt
    The file should contain the following:
    KATALON_OP_VERSION: 3.0.0
    June 3, 2024
     
    ### IMAGES TAG ###
    ENVOY: op-a55958afbcab500990aaf6bbaf58dd7ff5b56f97
    LICENSE_SERVER: op-a3fb4c2d0076902d84abba053e240b6bae6a503b
    AUTHORIZER: op-9f21f7c53b075ce222e1c2196288113327fa48e2
    KEYCLOAK: op-b89406c7794b8e30ec4906b8e9f55fd7566b2a5e
    KEYCLOAK_CONFIG_CLI: op-b11786b85dc318b2a12b612e5fc243e0533487f5
    REDIS: op-4786e459da28f99f4ade5700b467cc56baf734bd
    KAFKA: op-f96f1b540295dfbb9597e38837bef566ce2a4f70
    ZOOKEEPER: op-f3374d97e2245152cec93c0c8c9ad1d49eb5abd7
    TESTOPS: op-e4c2267e98cbdd770beeefbd6ffb3270d78c6495
    TESTOPS_ENGINE: op-ba1f17f9f5417ca001854b93b0b3e2fedee2418f
    ORGANIZING_BE: op-649a471d996ae61ab877abe3b29906aac6c5da75
    REPO_SCANNER: op-af0e9babeafec19c8309ed3e98469c1632504e65
     
    ### IMAGES ID ###
    ENVOY_ID: 5c7ce86459f0
    LICENSE_SERVER_ID: 5d8fd0ce786e
    AUTHORIZER_ID: 2697d9fc45bd
    KEYCLOAK_ID: bae44d368348
    KEYCLOAK_CONFIG_CLI_ID: 08ea2d10abfd
    REDIS_ID: 92714677dba2
    KAFKA_ID: 577b760f3875
    ZOOKEEPER_ID: b191a95f8d52
    TESTOPS_ID: bc8505e7d8dd
    TESTOPS_ENGINE_ID: d06b7736e9f2
    ORGANIZING_BE_ID: fc3d1ddb9185
    REPO_SCANNER_ID: 52d01a25eaa4

Set up TestOps storage​

To set up your TestOps, you need to create a folder for TESTOPS_FILE_STORAGE_PATH. In this example, the preferred configuration is TESTOPS_FILE_STORAGE_PATH=/opt/testops-data. If you choose a different path, replace /opt/testops-data with your preferred directory.
  1. Run the following command to create the TestOps storage directory:
    mkdir -p /opt/testops-data
  2. Set the correct permission for the directory by running the following command:
    chmod 755 /opt/testops-data

    If your storage directory differs, substitute your own path in place of /opt/testops-data.

Deploy the License Server and TestOps​

To start the deployment process for Katalon On-Premises, follow these steps to configure the environment and set up the License Server and TestOps.
  1. Navigate to the katalon-op directory.
    Use the following commands to go to the katalon-op directory and verify the files:
    cd katalon-op
    ls -al
    You should see the following files in the directory:
    drwxrwxr-x 3 root root       4096 Jun  4 07:56 .
    drwxr-xr-x 3 root root       4096 Jun  4 03:43 ..
    -rw-rw-r-- 1 root root        960 Jun  4 07:56 .env
    -rw-rw-r-- 1 root root       1090 Jun  3 08:59 Build-Info.txt
    -rw-rw-r-- 1 root root       6105 Jun  3 08:44 docker-compose.yml
    -rw-rw-r-- 1 root root 5033163363 Jun  3 08:59 images_3.0.0.tar.gz
    -rw-rw-r-- 1 root root       1305 Jun  3 08:44 katalon-op.crt
    -rw-rw-r-- 1 root root       1703 Jun  3 08:44 katalon-op.key
    drwxr-xr-x 2 root root       4096 Jun  4 04:32 logs
  2. Configure the .env file.
    Open the .env file and replace the placeholder values with your own information. Ensure you update the following:

    • Database information.

    • Email and password information.

    • TestOps storage path, URLs, domain certificate, and key.

      Note:
      • Ensure the admin password follows these guidelines:

        • Minimum of 8 characters.

        • Contains at least one uppercase letter, one lowercase letter, one special character, and one number.

        • The password must not start or end with a space.

    The .env file should contain basic and advanced settings for both HTTP and HTTPS scenarios, depending on your deployment. Refer to the following sample script guide to know which values to replace with your configuration:
    • HTTP scenario configuration
      ### Katalon-OP env

      ########### Basic Settings ###########

      # Database configs
      DB_HOST=host.docker.internal                  <= Replace your own
      DB_PORT=5432                                  <= Replace your own
      DB_USERNAME=postgres                          <= Replace your own
      DB_PASSWORD=admin                             <= Replace your own

      # Admin user configs
      ADMIN_EMAIL=admin@my.domain                   <= Replace your own
      ADMIN_PASSWORD=Admin@123                      <= Replace your own (see note)

      # Auth server configs
      AUTH_SERVER_URL=http://localhost:8082                         <= Replace your own

      # License Server configs
      LICENSE_SERVER_URL=http://localhost:8080                     <= Replace your own

      # TestOps configs (optional if testops profile is not used)
      TESTOPS_SERVER_URL=http://localhost:8081                        <= Replace your own
      TESTOPS_FILE_STORAGE_PATH=/opt/testops-data                     <= Replace your own

      ########### Advanced Settings ###########

      # HTTP config
      HTTP_PORT_1=8080              <= If apply HTTP, can adjust with your port or leave it by default
      HTTP_PORT_2=8081              <= If apply HTTP, can adjust with your port or leave it by default
      HTTP_PORT_3=8082              <= If apply HTTP, can adjust with your port or leave it by default

      # HTTPS configs
      HTTPS_PORT=                    <= Leave it empty by default
      CERT_PATH=                     <= Leave it empty by default
      KEY_PATH=                      <= Leave it empty by default
      KEY_PASSPHRASE=                <= Leave it empty by default

      # TestOps proxy configs (optional if testops profile is not used)
      PROXY_PROTO=http                      <= Leave it by default
      PROXY_HOST=                           <= If have Proxy, replace your own
      PROXY_PORT=                           <= If have Proxy, replace your own
      PROXY_USERNAME=                       <= If have Proxy, replace your own
      PROXY_PASSWORD=                       <= If have Proxy, replace your own
      PROXY_EXCLUDE_LIST=                   <= If have Proxy, replace your own
      TRUSTED_CA_CERT_PATH=                 <= If have an internal CA, replace your own
    • HTTPS scenario configuration
      ### Katalon-OP env

      ########### Basic Settings ###########

      # Database configs
      DB_HOST=host.docker.internal                  <= Replace your own
      DB_PORT=5432                                  <= Replace your own
      DB_USERNAME=postgres                          <= Replace your own
      DB_PASSWORD=admin                             <= Replace your own

      # Admin user configs
      ADMIN_EMAIL=admin@my.domain                   <= Replace your own
      ADMIN_PASSWORD=Admin@123                      <= Replace your own (see note)

      # Auth server configs
      AUTH_SERVER_URL=https://login.kata-op.com                     <= Replace your own

      # License Server configs
      LICENSE_SERVER_URL=https://admin.kata-op.com                <= Replace your own

      # TestOps configs (optional if testops profile is not used)
      TESTOPS_SERVER_URL=https://testops.kata-op.com                        <= Replace your own
      TESTOPS_FILE_STORAGE_PATH=/opt/testops-data                           <= Replace your own

      ########### Advanced Settings ###########

      # HTTP config
      HTTP_PORT_1=8080              <= Leave it by default
      HTTP_PORT_2=8081              <= Leave it by default
      HTTP_PORT_3=8082              <= Leave it by default

      # HTTPS configs
      HTTPS_PORT=443                    <= If apply HTTPS, input 443
      CERT_PATH=                        <= Replace your own
      KEY_PATH=                         <= Replace your own
      KEY_PASSPHRASE=                   <= Replace your own if have

      # TestOps proxy configs (optional if testops profile is not used)
      PROXY_PROTO=http                      <= Leave it by default
      PROXY_HOST=                           <= If have Proxy, replace your own
      PROXY_PORT=                           <= If have Proxy, replace your own
      PROXY_USERNAME=                       <= If have Proxy, replace your own
      PROXY_PASSWORD=                       <= If have Proxy, replace your own
      PROXY_EXCLUDE_LIST=                   <= If have Proxy, replace your own
      TRUSTED_CA_CERT_PATH=                 <= If have an internal CA, replace your own

Configure SSL certificate FQDNs/URLs​

If you are running the License Server with Katalon Platform, you must configure three sub-domains, known as Fully Qualified Domain Names (FQDNs). An FQDN is the complete domain name that specifies the exact location of a server or resource on the internet.

The required sub-domains include:

  • admin.kata-op.com (for the License Server)

  • testops.kata-op.com (for TestOps)

  • login.kata-op.com (for the Authorizer)

Katalon recommends using a Wildcard SSL certificate to secure these sub-domains.

  1. Prepare the SSL certificate and key.
    • Ensure you have the SSL certificate and key files stored in a directory on your server.

    • If your certificate and key files are stored in a different directory, replace the paths accordingly.

  2. Update the .env file.
    The following is an example of how to configure the HTTPS settings in the .env file, assuming the certificate and key files are located in /katalon/katalon-3.0.0/:
    # HTTPS config
    HTTPS_PORT=443
    CERT_PATH=/katalon/katalon-3.0.0/your-domain.crt
    KEY_PATH=/katalon/katalon-3.0.0/your-domain.key
    KEY_PASSPHRASE=

    If the certificate and key are stored elsewhere, substitute your directory path for /katalon/katalon-3.0.0/.

Run the application with Docker Compose​

To start the Katalon On-Premises application, run the corresponding Docker Compose command depending on your deployment plan.
Start Katalon On-Premises.
  1. If using only the License Server, enter the following command:
    docker compose up -d
  2. If using both the License Server and TestOps, run this command instead:
    docker compose --profile testops up -d
Once the process starts, you can monitor the containers as they initialize. The startup process may take some time to complete. The application will be ready once all services have started, as shown in the image below:

Was this page helpful?