Installing VISULOX Cluster

1. Introduction

This guide describes the process of provisioning and validating a highly available VISULOX Cluster consisting of Master, Gateway and Worker nodes. The setup follows a strict order, where each component depends on configuration and credentials created in earlier steps

2. Definitions

There are three types of server nodes in a VISULOX Cluster, all served by NGINX installed on them:

Master

• Contains: Core, Portal, Connector

• Must be installed first

• Some Core logic runs only on the Master

• There can be only one Master

Gateway

• Contains: Connector

• Responsible for load balancing

• There can be multiple Gateways

Worker

• Contains: Core, Portal, Connector

• There can be multiple Workers

Core

• Core means the VISULOX Core application, the amitego legacy application written in TCL language.

Portal

• Portal is the newly developed VISULOX application written in Go. It includes several APIs and serves as the user contact point for both the UI4 panel and the dashboard panel. It communicates with VISULOX Core via the Connector.

Connector

• Connector is a Golang project that interfaces between the portal and core. VISULOX Core uses various protocols, including Socket, HTTP, and SOAP. The Connector project wraps all core APIs, regardless of protocol, into an HTTP REST API.

3. Dependencies

VISULOX requires:

• PostgreSQL

• KeyDB

These can:

• Be installed separately before the Master installation

• OR be installed automatically during Master setup

4. Overview

Setting up a VISULOX cluster is a step-by-step process that builds a distributed system consisting of Master, Gateway, and Worker nodes. The setup must follow a strict order, as each stage depends on configuration and credentials created in earlier steps .

4.1 Conceptual Flow of the System

The VISULOX Cluster is composed of three roles:

• Master Node → Central control (Core, Portal, Connector)

• Gateway Node(s) → Entry point and traffic routing

• Worker Node(s) → Execution and scaling layer

Together, they form a system where the Master manages configuration, the Gateway exposes access, and Workers handle workload execution. This separation enables scalability and high availability.

4.2 Setup Process

The setup follows a top-down approach, where components are added and connected progressively.

Step 1 — Environment Preparation

Before installation:

• Ensure system time is synchronized

• Prepare at least three servers

• Verify required dependencies (PostgreSQL, KeyDB, networking)

This step is critical, as issues here affect the entire setup.

Step 2 — Master Installation

The Master is installed first and initializes the cluster.

• Sets up VISULOX Core and Portal services

• Stores configuration and VISULOX Cluster state

• Defines the Gateway address

It also generates the credentials required for other nodes to join.

Step 3 — Gateway Setup

The Gateway is installed next and connects to the Master.

• Registers itself in the VISULOX Cluster

• Establishes secure communication

• Enables external access and request routing

At this stage, the system becomes accessible but not yet scalable.

Step 4 — Worker Deployment

Workers are added to provide execution capacity.

• Install required components

• Synchronize keys with the Master

• Attach to the VISULOX Cluster

This enables distributed execution and allows horizontal scaling.

Step 5 — Worker Registration & Integration

Each Worker is registered in the Portal layer and fully integrated.

• Makes Workers visible to the system

• Enables proper request routing

• Finalizes communication with the Master

5. Installation Order (Mandatory)

1. Master

2. Gateway

3. Worker

⚠️ During Master installation:

• The gateway hostname and IP must be provided

• The master does not work properly before the gateway installation is completed

6 Prerequisites

6.1 Servers

• At least 3 servers needed for clustering:

  • 1 Master

  • 1 Gateway

  • 1 Worker

6.2 Time Synchronization (Mandatory)

⚠️ Critical Requirement

The server system time must be correct and synchronized before running:

• visulox start

• setup-master

• Any Docker-based service initialization (e.g., PostgreSQL container)

An incorrect system time can cause:

• TLS certificate validation failures

• Docker image pull errors

• PostgreSQL container startup failure

• setup-master interruptions

Example failure:

tls: failed to verify certificate: x509: certificate has expired or is not yet valid
current time 2026-02-16T14:04:39+01:00 is before 2026-02-19T20:57:44Z

Fix command:

REMOTE_TIME=$(curl -kfsSI https://www.google.com | awk -F': ' '/^[Dd]ate:/{print $2}' | tr -d '\r')
echo "$REMOTE_TIME"
sudo date -s "$REMOTE_TIME"
sudo hwclock --systohc

7. Master Setup

7.1 Minimum Requirements

• 2 Core CPU

• 4 GB RAM (8 GB recommended)

7.2 Installation:

7.2.1 Setting up the Master server in cluster mode

The installation process is the same for single-instance mode (Installing VISULOX) with one exception: in setup-master, you must provide the gateway hostname.

Required Version

Latest VISULOX 5 Core version

7.2.2 Generating Connector Secret for Master

A Connector should be defined on the Master server. The Main server generates a secret key for this Connector. The Gateway needs this key to connect to the Master Connector.

To create the Gateway Connector, run this on Master:

sudo /opt/visulox-portal/bin/vlx-portald create-maingateway-connector -c /opt/visulox-portal/configs/config.json --output json

Sample output format would be like:

{"secret":"63301a03-3c1b-4ec5-9590-a84961304ba2"}

Parameters:

• Use --output json or --output secret to get the key in JSON or plain format.

• -c /opt/visulox-portal/configs/config.json provide the config file of the Portal server. It contains Portal database credentials which is needed to create Connector in Portal databse.

8. Gateway Setup

8.1 Installing Main Gateway (or Connector) RPM

Remove the old version if it exists:

sudo dnf remove vlx-connector vlx-portal vlx-portal-rte -y || true
sudo rm -rf /opt/visulox-portal* || true
sudo rm -rf /var/vlx-portal || true
sudo rm -f /opt/visulox-portal/.setup_done || true
sudo systemctl daemon-reload || true

vlx-connector contains Main Gateway functionality plus additional Connector-related components and dependencies.

Install the full Connector package:

sudo dnf install vlx-connector-*.rpm -y

Note that vlx-connector requires additional server preparation steps and dependencies. Before installing it, complete the prerequisites described in the Server Preparation section of the Visulox Core & Portal Installation Guide: Installing Visulox (Server preparation)

8.2 Gateway Setup (setup-maingateway)

After installing the RPM, run the Gateway setup wizard.

The setup wizard guides you through the required configuration and generates the Gateway configuration files.

The setup can be used in two modes:

Interactive Setup

On the Gateway server, run:

sudo /opt/visulox-portal-connector/bin/vlx-connectord setup-maingateway

Regarding the Connector Secret prompt, use the secret of the Gateway Connector that was created in Section 7.2.2.

During the setup, you will be asked:

Enter XPRA Route Type [safe/performant] (default safe):

XPRA Route Type

safe (recommended)

• All XPRA traffic is routed through the Gateway over HTTPS (port 443).

• XPRA daemon ports do not need to be exposed externally.

• Simpler firewall configuration.

• Better security posture.

• Suitable for most deployments.

performant

• The Gateway connects directly to the XPRA daemon ports.

• Eliminates one proxy hop and may provide slightly better performance.

• Requires multiple XPRA-related ports to be reachable between clients and the Gateway.

• Increases the number of exposed network ports and firewall rules.

In most cases, safe should be used unless there is a specific performance requirement that justifies exposing additional ports.

Non-Interactive Setup

In some situations, such as automated deployments or scripting, you may want to run the setup without interactive prompts.

Generate a template file:

sudo /opt/visulox-portal-connector/bin/vlx-connectord setup-maingateway --get-template /tmp/vlx-portal

This command creates:

/tmp/vlx-portal/setup_maingateway_template.json
/tmp/vlx-portal/setup_maingateway_template.json_README.txt

A default-generated template looks similar to:

{
  "connector_secret": "",
  "gateway_host": "",
  "gateway_port": "8180",
  "main_server_host": "",
  "main_server_port": "8080",
  "dns_resolver": "172.17.3.1",
  "xpra_route_type": "safe"
}

Input definitions:

connector_secret — UUID of the Main Gateway connector from the Portal database (required).

gateway_host     — Public URL used by clients to access the Gateway
                   (for example: https://access.example.com) (required).

gateway_port     — HTTPS listen port used by NGINX on this host.
                   Default: 8180.

main_server_host — Portal hostname or IP address (required).

main_server_port — Portal REST API port.
                   Default: 8080.

dns_resolver     — Optional comma-separated DNS resolver IPs used by NGINX.
                   If empty, system DNS resolvers are used.

xpra_route_type  — Optional.
                   Values: "safe" or "performant".
                   Default: "safe".

After filling the template file, run the setup using the JSON file:

sudo /opt/visulox-portal-connector/bin/vlx-connectord setup-maingateway \
  --file /tmp/vlx-portal/setup_maingateway_template.json

8.3 Verifying Installation

cat /etc/nginx/includes/visulox-gateway-main-upstream-servers.conf

Expected: Master server IP is listed.

8.4 Verifying Setup

Visit:

https://$gateway_domain:8180/ui4/login

Test both: VispraClient and WebClient.

8.5 Verifying Network Accessibility (Troubleshooting)

This step is only required if sessions fail to start or applications become stuck during launch.

The required network connectivity depends on the selected XPRA Route Type:

Safe Mode

In safe mode, all XPRA traffic is routed through the Gateway using HTTPS. XPRA daemon ports are not exposed and do not need to be reachable from clients.

Verify that:

• The Gateway can reach the Master and Worker Portal services.

• HTTPS communication between Gateway, Master, and Worker nodes is working.

• DNS resolution is functioning correctly between cluster nodes.

Performant Mode

In performant mode, the Gateway connects directly to XPRA daemon ports on the Master and Worker nodes. Therefore, the Gateway must be able to reach the XPRA port range:

14600-15600/tcp

To verify connectivity, select a test port from this range.

On the Master or Worker server:

nc -l -p <PORT_NUMBER>

On the Gateway server:

nc -w 3 <SERVER_HOSTNAME_OR_IP> <PORT_NUMBER>

After the connection is established, type a test message such as:

Hello

If the message appears on the receiving server, connectivity is working correctly.

If the connection fails, traffic may be blocked by:

• The Gateway server firewall

• The Master or Worker server firewall

• A firewall between the servers

• Network routing restrictions

Note: This test verifies only basic TCP connectivity and does not validate Visulox configuration or application functionality.

9. Worker Setup

9.1 Core and Portal RPM Installation

Only Core and Portal RPMs should be installed on Worker as explained here as mentioned in Installing VISULOX from 1st step to Step 2. So, it means that no setup-master is needed at this point.

9.2 Staring and Attaching Core

Then start Core service and attach it:

# Start services
sudo visulox start
sudo visulox portal attach -proxy

9.3 Key synchronization

Both Visulox Core modules must have the same key; if their keys are not the same, they cannot be configured as a cluster.

Find the key on Master in this path:

/opt/visulox/etc/key

And copy it to the same path in Worker.

Restart Worker Visulox when key is copied from Master:

sudo visulox restart

9.4 Firewall Configuration

Visulox core nodes communicate on specific port ranges. So, we need to open those ports in the firewalls of both Master and Worker(s) servers.

Create:

sudo touch /usr/lib/firewalld/services/vlx.xml

Content:

<service>
  <short>VISULOX Firewall Rules</short>
  <description>The following rules are needed for the VISULOX Service and the VISULOX Components.</description>
  <port protocol="tcp" port="6000-6500"/>
  <port protocol="tcp" port="7001-7010"/>
  <port protocol="tcp" port="21"/>
  <port protocol="tcp" port="1443"/>
  <port protocol="tcp" port="8114"/>
  <port protocol="tcp" port="8115"/>
</service>

Apply:

sudo firewall-cmd --permanent --zone=public --add-service=vlx
sudo firewall-cmd --reload

9.5 Attaching Worker to Master

At the final stage, we should attach the Visulox Core of the Master server to that of the worker server(s).

Run on Master:

sudo -s
cd ~
visulox attach $domain_of_worker_server

Expected output:

attached node vSFTESTWORKERSERVER06 at location 'STANDARD' zone 'STANDARD'
etcd cluster: added vSFTESTMASTERSERVER06
etcd client started

Then check:

visulox status

Expected Output (Example)

---------------------------------------------------------------------------------------------------------------------
|                  node | location |     zone | nodeinfo | status | archive |    servicestarttime |         version |
---------------------------------------------------------------------------------------------------------------------
| vSFTESTMASTERSERVER05 | STANDARD | STANDARD | STANDARD |     up |         | 2026-03-05 12:47:39 | 5.alpha-vlxxpra |
| vSFTESTWORKERSERVER05 | STANDARD | STANDARD | STANDARD |     up |         | 2026-03-05 12:46:34 | 5.alpha-vlxxpra |
---------------------------------------------------------------------------------------------------------------------

9.6 Troubleshooting

visulox integrity
journalctl -u visulox -n 100 -f

visulox log -l info
visulox log -l debug
visulox log -l error

10. Registering Worker in Master

You should insert a Portal server in the database for the Worker server you want to attach to the Visulox Cluster.
To do so, in the Master server, run the following command with the domain and IP address of the Worker server:

sudo /opt/visulox-portal/bin/vlx-portald create-worker-portal-server -c /opt/visulox-portal/configs/config.json --domain $WORKER_SERVER_DOMAIN --server-ip $WORKER_SERVER_IP

For example:

sudo /opt/visulox-portal/bin/vlx-portald create-worker-portal-server -c /opt/visulox-portal/configs/config.json --domain sf-test-worker-server-10.tbsol.de --server-ip 172.20.0.25

• You can pass the --server-ip if you want, also to pass the IP of the worker server, but keep in mind that if the DNS is not configured, or the DNS doesn’t have a record of the $WORKER_SERVER_DOMAIN linked to the $WORKER_SERVER_IP, you will receive an error.

• If you want to receive the command result in a JSON format, you can add the --output json argument. For example:

  sudo /opt/visulox-portal/bin/vlx-portald create-worker-portal-server -c /opt/visulox-portal/configs/config.json --domain <hostname.domain> --server-ip <xxx.xxx.xxx.xxx> --output json {"server_name":"<logservernameXXX>","domain":"<hostname.domain>","server_ip":"<xxx.xxx.xxx.xxx>","secret":"xxxxxxxxxxxxxxxxxx"}
  

• If you only want to receive the portal secret by running the above command, you can add the --output secret switch to the first command. For example:

  sudo /opt/visulox-portal/bin/vlx-portald create-worker-portal-server -c /opt/visulox-portal/configs/config.json --domain <hostname.domain> --server-ip <xxx.xxx.xxx.xxx> --output secret xxxxxxxxxxxxxxxxxx
  

11. Installing Portal On Worker

11.1 Portal Installation

Download the desired RTE, Portal, and Connector RPMs to /tmp/vlx-portal/.

Then run this on the Worker:

cd /tmp/vlx-portal

sudo dnf install vlx-portal-rte-*.rpm -y
sudo dnf install vlx-portal-*.rpm -y
sudo dnf install vlx-connector-*.rpm -y

11.2 Portal Setup

From the Worker:

sudo /opt/visulox-portal/bin/vlx-portald setup-node

This command will ask for the portal secret. You should use the secret you received in last step.

Running Setup (Non-interactively)

In some cases, you may not want to enter the inputs of the setup-node command interactively. For example, if you are writing a script, you need to run this command in a non-interactive mode to have control over the inputs.
To do so, you need to create template files for the setup command to run. You need to run the following command:

/opt/visulox-portal/bin/vlx-portald setup-node --get-template /tmp/vlx-portal

After running the above command, a setup_node_template.json template file and a setup_node_template_README.txt file will be created in the /tmp/vlx-portal directory.

An example of a default-generated template file looks like this:

{
  "master_ip": "",
  "master_port": "8080",
  "secret": "",
  "dns_resolver_ips": [
    "172.17.3.1"
  ],
  "keydb_tls": {
    "ca_cert_path": "",
    "client_cert_path": "",
    "client_key_path": ""
  },
  "postgresql_tls": {
    "ca_cert_path": "",
    "client_cert_path": "",
    "client_key_path": ""
  }
}

You need to fill in the required items of this template file by reading the README file. Then, consider you have prepared a setup JSON file using the template file named setup-node.json; You can run the setup node command non-interactively as follows:

sudo /opt/visulox-portal/bin/vlx-portald setup-node --file /path/to/setup-node.json

11.3 Verifying network accessibility

If there are issues with setting up sessions, see Step 8.5 and check the range of 14600-15600/TCP.

12. Setting Up Additional Workers

• Recommended: at least 3 nodes (odd number)

• Repeat worker setup

13. Final Testing

https://$gateway_domain:8180/ui4/login

Test with VispraClient and WebClient.