Insight Single Node Interactive Script Installation (recommended)

JFrog Installation & Setup Documentation

Content Type
Installation & Setup
ft:sourceType
Paligo

All install types are supported, including: Docker Compose, Linux Archive, RPM, and Debian.

The installer script provides you an interactive way to install Insight and its dependencies. All install types are supported. This installer should be used for Docker Compose.

Before you proceed with the installation, review the system requirements.

Operating Systems and Platform Support

The following table lists the supported operating systems and the versions.

Product

Debian

RHEL

Ubuntu

Windows Server

Amazon Linux

Insight

10.x, 11.x

8.x, 9.x

20.04, 22.04

Amazon Linux 2023

Operating Systems - End of Support

As part of JFrog commitment to maintain the security and reliability of the JFrog Platform, Artifactory will officially run with Node.js 20.x on all installation types from Artifactory 7.77.3.

Node.js 20.x provided with Linux Archive/Debian/RPM installations (non-containerized distributions) is not supported on the following operating systems.

Hence, these operating systems will no longer supported from Artifactory version 7.77.3.

Supported Platforms

The following table lists the supported platforms.

Product

x86-64

ARM64

Kubernetes

OpenShift

Insight

1.19+

Installation on Kubernetes environments is through Helm Charts. Supported Helm version is Helm 3+.

ARM64 Support

From version 7.41.4, Artifactory supports installation on ARM64 architecture through Helm and Docker installations. You must set up an external database as the Artifactory database since Artifactory does not support the bundled database with the ARM64 installation. Artifactory installation pulls the ARM64 image automatically when you run the Helm or Docker installation on the ARM64 platform.

ARM64 support is also available for Xray, Pipelines (in Helm installation), and Insight.

Database and Third-Party Applications in Insight

A database is required, which is fundamental to management of Insight and is also used to store cluster wide configuration files. Currently PostgreSQL is supported, and any change to configuration requires restarting all Insight nodes for changes to take effect.

Insight supports the following versions of PostgreSQL.

  • 15.x

  • 13.x

  • 12.x

An Elasticsearch database is required to store the data from which Insight generates trends and charts.

Insight supports the following versions of Elasticsearch.

  • 7.17.1 (for Insight 1.11.3 and later)

  • 7.16.2 (for Insight 1.5.0 to 1.10.2)

  • 7.15.1 (for Insight 1.2.3 to 1.30)

  • 7.14.1 (for Insight 1.0.1 to 1.1.3)

Insight Network Ports

Insight uses the 8082 port by default for external communication.

Insight uses the following internal ports by default for communication with JFrog Platform microservices.

  • 8080 for the Insight Server

  • 8082, 8046, 8047, and 8049 for the Router

  • 8087 for Insights

  • 5432 for PostgreSQL (if you use the bundled Postgres database)

  • 9200 for Elasticsearch (if you use the bundled Elasticsearch)

Complete the following steps to install the product.

  1. Download Insight.

  2. Extract the contents of the compressed archive and go to the extracted folder.

    Docker Compose/RPM/DEB

    tar -xvf jfrog-insight-<version>-<compose|rpm|deb>.tar.gz
    cd jfrog-insight-<version>-<compose|rpm|deb>

    OS user permissions for Linux archive

    When running Insight, the installation script creates a user called insight by default, which must have run and execute permissions on the installation directory.

    We recommend that you extract the Insight download file into a directory that gives run and execute permissions to all users such as /opt.

    mv jfrog-insight-<version>-linux.tar.gz /opt/
    cd /opt
    tar -xf jfrog-insight-<version>-linux.tar.gz
    mv jfrog-insight-<version>-linux insight
    cd insight

    Linux Archive

    mv jfrog-insight-<version>-linux.tar.gz /opt/
    cd /opt
    tar -xf jfrog-insight-<version>-linux.tar.gz
    mv jfrog-insight-<version>-linux insight
    cd insight

    .env file included within the Docker-Compose archive

    The .env file is used by docker-compose and is updated during installations and upgrades.

    Some operating systems do not display dot files by default. If you make any changes to the file, remember to backup before an upgrade.

  3. Run the installer script.

    The script prompts you with a series of mandatory inputs, including the jfrogURL (custom base URL) and joinKey.

    Docker Compose

    ./config.sh

    RPM/DEB

    ./install.sh

    Linux archive

    ./install.sh --user <user name> --group <group name>
     
    -h | --help                                       : [optional] display usage
    -u | --user                                       : [optional] (default: insight) user which will be used to run the product, it will be created if its unavailable
    -g | --group                                      : [optional] (default: insight) group which will be used to run the product, it will be created if its unavailable

    Check prerequisites for Insight in Linux Archive before running the install script.

  4. Validate and customize the product configuration (optional), including the third party dependencies connection details and ports.

  5. Start and manage the Insight service.

    systemd

    systemctl start|stop insight.service

    systemv

    service insight start|stop

    Docker Compose

    cd jfrog-insight-<version>-compose
    docker-compose -p insight up -d
    docker-compose -p insight ps
    docker-compose -p insight down

    Linux archive

    insight/app/bin/insight.sh start|stop

    You can install Insight as a service in a Linux archive installation. Refer start Insight section under Linux Archive Manual Installation for more details.

  6. Access Insight from your browser at: http://<jfrogUrl>/ui/ and go to the Dashboard tab in the Application module in the UI.

  7. Check the Insight log.

    tail -f $JFROG_HOME/insight/var/log/console.log

    Configure log rotation of the console log

    The console.log file can grow quickly since all services write to it. For more information, see configure the log rotation.Configuring Log Rotation for Tomcat

After installing and before running Insight, you may set the following configurations.

Where to find the system configurations?

You can configure all your system settings using the system.yaml file located in the $JFROG_HOME/insight/var/etc folder. For more information, see Insight YAML Configuration.

If you don't have a System YAML file in your folder, copy the template available in the folder and name it system.yaml.

For the Helm charts, the system.yaml file is managed in the chart’s values.yaml.

Artifactory Connection Details

Insight requires a working Artifactory server and a suitable license. The Insight connection to Artifactory requires 2 parameters:

  • jfrogUrl - URL to the machine where JFrog Artifactory is deployed, or the load balancer pointing to it. We recommend that you use DNS names rather than direct IPs. For example, http://jfrog.acme.com instead of http://10.20.30.40:8082.

    Set it in the Shared Configurations section of the $JFROG_HOME/insight/etc/system.yaml file.

  • join.key - This is the "secret" key required by Artifactory for registering and authenticating the Insight server.

    You can fetch the Artifactory joinKey (join Key) from the JPD UI in the Administration module | User Management | Settings | Join Key.

    Set the join.key used by your Artifactory server in the Shared Configurations section of the $JFROG_HOME/insight/etc/system.yaml file.

Change PostgreSQL Database Credentials

Insight comes bundled with a PostgreSQL Database out-of-the-box, which comes pre-configured with default credentials.

Note

These commands are indicative and assume some familiarity with PostgreSQL. Do not copy and paste them. For docker-compose, you need to ssh into the PostgreSQL container before you run them.

To change the default credentials:

# Access PostgreSQL as the insight user adding the optional -W flag to invoke the password prompt
$ psql -d insight -U insight -W
# Securely change the password for user "mission_control". Enter and then retype the password at the prompt.
\password insight
# Verify the update was successful by logging in with the new credentials
$ psql -d insight -U insight -W
Change Elasticsearch Credentials

Search Guard tool is used to manage authentication. To change password for the default user, Search Guard accepts a hash password to be provided in the configuration.

  1. Obtain the username used to access Elasticsearch from $JFROG_HOME/insight/var/etc/system.yaml available at elasticsearch.username.

  2. Generate the hash password by providing the password(in text format) as input

    $ELASTICSEARCH_HOME/plugins/search-guard-<major_version_number>/tools/hash.sh -p <password_in_text_format>
  3. Update the configuration of the default user with the output from the previous step.

    vi $ELASTICSEARCH_HOME/plugins/search-guard-<major_version_number>/sgconfig/sg_internal_users.yml
    #Scroll in the file to find an entry for the username of the default user
    #Update the value for "hash" with the hash content obtained from previous step
    <default_username>:
       hash: <hash_output_from_previous_step>
  4. Run the command to initialise Search Guard.

Change Elasticsearch Credentials in Docker-Compose
  1. Stop Docker services.

    docker-compose -p insight down
  2. Change the password in docker-compose.yaml and system.yaml to the new password.

    In docker-compose.yaml:
    
    - ELASTICSEARCH_PASSWORD=<new_password>
     
    In system.yaml:
    
    shared.elasticsearch.password
  3. Move the following file to a backup directory.

    mv <JFROG_HOME>/insight/var/data/elasticsearch/sgconfig/sg_internal_users.yml /$HOME/sg_internal_users.yml.backup
  4. Restart Docker services.

    docker-compose -p insight up -d
Add certificates to connect to external Elasticsearch over SSL

To use an external Elasticsearch over an SSL connection, you must copy the certificate files to the trusted folder in the Insight installation ($JFROG_HOME/insight/var/etc/security/keys/trusted) and restart Insight services.

Set your PostgreSQL and Elasticsearch connection details in the Shared Configurations section of the $JFROG_HOME/insight/var/etc/system.yaml file.

Load a custom certificate to Elasticsearch Search Guard

If you prefer to use the custom certificates when Search Guard enabled with tls in Elasticsearch, you can use the search-guard-tlstool to generate Search Guard certificates.

The tool to generate Search Guard certificates is available at $JFROG_HOME/app/third-party/elasticsearch/search-guard-tlstool-1.6.tar.gz. For more information about generating certificates, see Search Guard TLS Tool.

  1. Run the tool to generate the certificates.

    tar -xvf $JFROG_HOME/app/third-party/elasticsearch/search-guard-tlstool-1.6.tar.gz
    cp $JFROG_HOME/app/third-party/elasticsearch/config/tlsconfig.yml $JFROG_HOME/app/third-party/elasticsearch/search-guard-tlstool-1.8/config
    cd $JFROG_HOME/app/third-party/elasticsearch/search-guard-tlstool-1.8/tools
    ./sgtlstool.sh -c ../config/tlsconfig.yml -ca -crt # folder named "out" will be created with all the required certificates,
    cd out
  2. Copy the generated certificates (localhost.key, localhost.pem, root-ca.pem, sgadmin.key, sgadmin.pem ) to the target location based on the installer type.

    Native

    cp localhost.key localhost.pem root-ca.pem sgadmin.key sgadmin.pem  /etc/elasticsearch/certs/

    Docker Compose

    cp localhost.key localhost.pem root-ca.pem sgadmin.key sgadmin.pem $JFROG_HOME/insight/var/data/elasticsearch/certs
Configure a custom Elasticsearch role

The Search Guard tool is used to manage authentication. By default, an admin user is required to authenticate Elasticsearch. As an alternative to this, you can configure a new user to authenticate Elasticsearch by assigning a custom role with permissions for the application to work.

  1. Add the following snippet to define a new role with custom permissions in $ELASTICSEARCH_HOME/plugins/search-guard-<major_version_number>/sgconfig/sg_roles.yml.

    <role_name>:
      cluster_permissions:
        - cluster:monitor/health
        - cluster:monitor/main
        - cluster:monitor/state
        - "indices:admin/template/get"
        - "indices:admin/template/delete"
        - "indices:admin/template/put"
        - "indices:admin/aliases"
        - "indices:admin/create"
      index_permissions:
        - index_patterns:
            - "active_*"
          allowed_actions:
            - "indices:monitor/health"
            - "indices:monitor/stats"
            - "indices:monitor/settings/get"
            - "indices:admin/aliases/get"
            - "indices:admin/get"
            - "indices:admin/aliases"
            - "indices:admin/create"
            - "indices:admin/delete"
            - "indices:admin/rollover"
            - SGS_CRUD
  2. Add the following snippet to add a new user in $ELASTICSEARCH_HOME/plugins/search-guard-<major_version_number>/sgconfig/sg_roles.yml/sg_internal_users.yml.

    <user_name>:
      hash: <Hash_password>
      backend_roles:
        - "<role_name>"   //role_name defined in previous step
      description: "<description>"
  3. Run the following command to generate a hash password.

    $ELASTICSEARCH_HOME/plugins/search-guard-<major_version_number>/tools/hash.sh -p <clear_text_password>
  4. Add the following snippet to map the new username to the role defined in the previous step in $ELASTICSEARCH_HOME/plugins/search-guard-<major_version_number>/sgconfig/sg_roles.yml/sg_roles_mapping.yml

    <role_name>:
      users:
        - "<user_name>"
  5. Initialize Search Guard to upload the changes made in the configuration.

  6. Set the new credentials in $JFROG_HOME/insight/etc/system.yaml file:

    shared:
        elasticsearch:
               username: <user_name>
               password: <clear_text_password>
  7. Restart Insight services.