Quick Start Single-Node Linux Installation

Quickly deploy a complete single-node instance with all platform services on one machine. Single-node installations are suitable for testing, proof-of-concept, and small-scale environments.

Overview

The single-node installation sets up all components (Frontend Node, Backend Nodes, and Scan Node) on a single machine. This configuration is recommended for:

• Small deployments with limited data volume

• Testing environments

• Proof-of-concept

Prerequisites

Operating System Requirements

The following Linux operating systems are supported for the node server:

• Officially supported: Red Hat Enterprise Linux 9+

• Compatible (expected to work): CentOS 9+, Alma Linux 9+

System requirements

The node server needs to meet the following minimum requirements:

Install User

The installing user must have sudo rights on the node in order to use required scripts such as tune.sh.

Network and Firewall

Review the following network and firewall considerations:

Internal Services: There are no network requirements for internal service traffic as all services are contained on a single node in this configuration.

Optional: Provide Your Own Certificate Requirements

The platform uses mutual TLS (mTLS) for secure authenticated communication between all services and server components.

All required certificates can be generated and self-signed, or you can provide your own certificates.

If you intend to bring your own certificates (BYOC) from a public CA or enterprise PKI rather than using self-signed installer-generated certificates, review BYOC: Prerequisites. Ensure prerequisites are met and determine all required install configuration details for proper certificate management.

External Domain Name Requirements

A single external FQDN for AgileSec platform access is required. When assigning configuration variables during installation instructions in provided guides, the external FQDN will be <analytics_hostname>.<analytics_domain>.

The following format is recommended: agilesec.<external domain>

For example: agilesec.dilithiumbank.com.

Prepare Installation Files

Ensure your node meets the minimum memory, CPU, and disk requirements.

1. Download the installation zip archive from the Keyfactor download portal to the node server.

2. Extract the zip archive <installer_package>.zip to your preferred install location installer_dir:

   unzip -d $installer_dir <installer_package>.zip
   cd $installer_dir
   

   Note: To install unzip on RHEL, run sudo dnf install unzip.

3. Ensure the installation script is executable:

   Java

   cd $installer_dir
   chmod +x install_analytics.sh
   

Create a .pass Password file

It is highly recommended users create a .pass file for non-interactive mode. When running in non-interactive mode, the install_analytics.sh script reads the admin password from a .pass file.

By default, password requirements include minimum 14 characters, at least 1 uppercase letter, at least 1 number, and at least 1 special character from `@ ! # $ & ?`.

1. Copy the example file: cp .pass.example .pass .

   1. To see all files, including files starting with a ., use ls -a

2. Edit .pass and set admin_password. Save the file and exit the editor.

3. Set secure permissions: chmod 600 .pass

Installation Overview

The installation can be performed in two modes: Interactive (default) or Non-Interactive (for automated/CI-CD deployments).

Non-Interactive Mode

All key installation scripts support an optional --non-interactive (or -n) flag to skip confirmation prompts, enabling fully automated deployments.

Step 1: Prepare the Environment

Ensure you have the installer package and your node meets the minimum memory and CPU requirements.

Update Single-Node Configuration

Environment configuration is required before starting the installation. A configuration file with default values for a single-node installation is available at generate_envs/single_node_config.conf. This file will be used by generate_envs.sh.

You may use the default values for all settings. However, it is recommended to review and update the following settings for single-node installations:

cd $agilesec_install_dir
sudo ./scripts/manage.sh start haproxy

cd $agilesec_install_dir
./scripts/manage.sh stop haproxy

Generate Configuration File for Single-Node Installation

Run the following command:

cd $installer_dir
./generate_envs/generate_envs.sh -t single-node

generate_envs.sh will copy $installer_dir/generate_envs/generated_envs/env.backend-1env.single_node to $installer_dir/.env.

The script has the following additional option flags available. Installation options can also be found by running ./generate_envs/generate_envs.sh --help.

Setup Certificates

Either generate and self-sign all required certificates using generate_certs.sh, or use certificates issued by your own CA. For POCs and first-time installations, it is recommended you use installer-generated certificates.

Run the following command to generate and self-sign all required certificates:

cd $installer_dir/certificates/
./generate_certs.sh
cd ..

This command will populate the required certificate files under the certificates directory.

For additional Certificate Management options and details, including using your own certificates, see On-Prem Certificates Management Guide.

External Browser FQDN Access Setup

Ensure external computer(s) where you will be accessing the AgileSec Platform UI from have at least one of the following for browser access:

1. Recommended for general multi-computer access: A DNS entry for <analytics_hostname>.<analytics_domain> pointing to the node’s IP address.

2. For quick proof of concept, test cases, or single computer access: An entry in your /etc/hosts for <analytics_hostname>.<analytics_domain> pointing to the node’s IP address.

Create a .pass Password file

It is highly recommended users create a .pass file for non-interactive mode. When running in non-interactive mode, the install_analytics.sh script reads the admin password from a .pass file. To set this up:

1. Copy the example file: cp .pass.example .pass .

   1. To see all files, including files starting with a ., use ls -a

2. Edit .pass and set admin_password. Save the file and exit the editor.

3. Set secure permissions: chmod 600 .pass

Step 2: Install the Platform

Check Environment Setup

Make sure settings file $installer_dir/.env is present.

Run tune.sh Script

cd $installer_dir
sudo ./scripts/tune.sh -u <username>

tune.sh updates the following:

1. System settings for Sysctl settings. Recommended values are:

   1. vm.max_map_count = 262144

   2. fs.file-max = 65536

2. Security settings in /etc/security/limits.conf for file descriptors and number of threads. These settings are needed by OpenSearch:

   1. <non-root-user> - nofile 65536

   2. <non-root-user> - nproc 65536

   3. <non-root-user> soft memlock unlimited

   4. <non-root-user> hard memlock unlimited

3. Adds /etc/hosts entries on node server to support internal and/or external communication.

   1. Note: Only entries with private IP addresses for internal nodes are added to /etc/hosts by tune.sh

4. Installs internal CA chain into the node trust stores used by AgileSec components.

5. Install git binary

Alternately, you can perform the above steps manually.

The script has the following additional option flags available. Installation options can also be found by running sudo ./tune.sh --help.

Run Installation Script

./install_analytics.sh install [OPTIONS]

install_analytics install installs the software for the AgileSec node.

To run interactively (will prompt for admin password on console):

./install_analytics.sh install -u <user> -p $agilesec_install_dir

To run non-interactively (will use .pass file for password):

cd $installer_dir
./install_analytics.sh install -u <user> -p $agilesec_install_dir --non-interactive

If any required parameters are omitted, the script will prompt you to enter them interactively.

The script has the following option flags available. Installation options can also be found by running ./install_analytics.sh install --help.

URL and Login Info

After successful installation, the installer will output an install summary with login URLs and login info. This information can also be found in $installer_dir/INSTALL_SUMMARY.txt.

Web UI information example:

• Login URL: https://<analytics_hostname>.<analytics_domain>:<analytics_port>

• Username: admin@<org_domain>

• Password: <the admin password you entered at the beginning of install>

Example: End-to-End Non-Interactive Single-Node Install

cd $installer_dir

# Generate env config
./generate_envs/generate_envs.sh -t single-node --non-interactive

# Generate certificates
cd certificates/
./generate_certs.sh --non-interactive
cd ..

# Prepare .pass file
cp .pass.example .pass
# Edit .pass and set admin_password
chmod 600 .pass

# Run system tuning
sudo ./scripts/tune.sh -u <user>

# Install
./install_analytics.sh install -u <user> -p $agilesec_install_dir --non-interactive

Post-Installation Verification

Verify Service Health

From agilesec_install_dir, run ./scripts/manage.sh status to check the status of all services. If any service shows Not running, try restarting it. See Managing Services for instructions on starting and restarting services.

The following services should have Running status:

$ ./scripts/manage.sh status
SERVICE                   DESCRIPTION                              STATUS              
------------------------  ---------------------------------------- --------------------
opensearch                OpenSearch Search Engine                 Running (PID: 1450891)
opensearch-dashboards     OpenSearch Dashboards                    Running (PID: 1452817)
indexing                  Indexing Microservice                    Running (PID: 1451400)
haproxy                   HAProxy Load Balancer                    Running (PID: 1451285)
mongodb                   MongoDB Server                           Running (PID: 1451281)
kafka                     Kafka Server                             Running (PID: 1451295)
webui                     Web UI Microservice                      Running (PID: 1451316)
api                       Web API Microservice                     Running (PID: 1452924)
cbom                      CBOM Exporter Microservice               Running (PID: 1453074)
sm                        Security Manager Microservice            Running (PID: 1453083)
analytics-manager         Analytics Manager Microservice           Running (PID: 1451408)
ingestion                 Ingestion Microservice                   Running (PID: 1451419)
scheduler                 Scheduler Microservice                   Running (PID: 1451450)

Access the Platform UI

To log into the new Web UI, use the URL displayed at the end of the install or in $installer_dir/INSTALL_SUMMARY.txt:

For example, using the default settings:

• Login URL: https://agilesec.kf-agilesec.com:8443

• Username: admin@kf-agilesec.com

• Password: HelloWorld123456!

You will see a login screen like this:

After logging in, the Overview Dashboard should show 0 across all charts, as shown in the screenshot below: