VISULOX 5 Documentation
VISULOX 5 Documentation
Breadcrumbs

VISULOX Portal Architecture

VISULOX 5 Architecture

Introduction

In this document, the architecture of VISULOX 5 is described in detail. The goal of this document is to explain the different components of the system, how they are defined, how they interact with each other, and what responsibilities each part has.

The terminology used in this document follows specific naming conventions for each component of the system.

Table of Contents

1. VISULOX Core

VISULOX Core is defined as the central brain responsible for:

  • Managing policies

  • Recording sessions

  • Managing session lifecycle

This component is written in TCL and is essentially a modified version of VISULOX 4.

2. VISULOX Portal

VISULOX Portal is the main business logic controller responsible for defining and managing:

  • User Profiles

  • Applications

  • Application Servers

  • Relationships between them

2.1 Dependencies

For the system to start, the following dependencies must be available:

  • PostgreSQL: The central database used to store system data.

  • KEYDB: A key-value database used for message brokering and data storage.

2.2 Services Provided:

  • Client WebSocket: Each native client (VISULOX Client Wrapper), which runs XPRA on the user's machine, connects to VISULOX Portal through this service.

  • UI4 WebSocket: Each browser client that logs into VISULOX via a browser requires UI updates (UI4), which are delivered through this connection.

  • SOAP APIs: All requests sent from VISULOX Core are processed via SOAP protocol by VISULOX Portal.

  • Dashboard APIs: All APIs used in the Portal Console dashboard are provided by VISULOX Portal. These APIs are protected using a cookie set during login.

  • Internal APIs: All APIs required by internal subsystems (such as VISULOX Portal Connector or other Portal servers) are provided here. These APIs are protected using JWT. Each component has a defined secret and receives an Access Token and Refresh Token during a handshake process.

  • Admin APIs: All APIs required by administrators for programmatic interaction with the system. These APIs are similar to Dashboard APIs but differ in authentication and authorization mechanisms.

2.3 Important Notes

VISULOX Portal acts as a control unit.
It makes decisions and sends commands to other components but does not perform execution itself.

For example, it does NOT:

  • Create Frame Buffers

  • Control the lifecycle of Frame Buffers

  • Configure NGINX

  • Directly communicate with VISULOX Core APIs

The system is designed so that VISULOX Portal can run all services listed in section 2.2 or only a subset of them.

In host environments (bare-metal or VM), it is possible to install databases alongside VISULOX servers.

For example, in a cluster with 5 servers:

  • 2 servers may run VISULOX + databases

  • 3 servers may run VISULOX only

In this context:

  • Master (master0, master1) → servers with VISULOX + databases

  • Worker → servers with only VISULOX

In cloud environments, the concept of master/worker does not exist.
All servers are treated equally.

In VISULOX 5 architecture, databases are considered infrastructure, not part of the core product.
Therefore, customers are free to configure them as they prefer.

3. VISULOX Portal Connector

VISULOX Portal Connector acts as the execution arm of VISULOX Portal.

Since VISULOX v5 consists of multiple components (VISULOX Core, NGINX, XPRA), each using different protocols:

  • VISULOX Core → ZMQ + REST

  • NGINX → configuration files

  • XPRA → CLI APIs

The responsibility of the Connector is to implement communication with each component and execute Portal commands accordingly. Also, if a new component is added or replaced in future versions of the software, it is the responsibility of the Connector to build the bridge between the Portal and that component.

3.1 Dependencies

  • Portal Address: Address of at least one VISULOX Portal server

  • Secret: A defined secret for communication

3.2 Services Provided

  • RESTful API: Executes all commands received from VISULOX Portal, including operations on XPRA, NGINX, and VISULOX Core.

  • XPRA Integration:

    • Applies Portal commands to XPRA

    • Manages XPRA sessions

    • Performs cleanup Emulator Sessions

    • Works with AppLauncher for RDP/SSH execution

  • VISULOX Core Integration: Executes Portal commands on VISULOX Core.

  • NGINX Integration: Applies configuration changes to NGINX (Main Gateway) and updates it.

  • File Upload Handling: Handles uploads using the Tus protocol plugin.

  • Entra Login Integration: Handles Entra (Azure) login via plugin.

3.3 Notes

Connector is a binary that can run on Windows, Linux, and macOS. It can leverage the capabilities of each platform to serve the Portal.

The Connector application can provide either a single service or all services together.

If the Connector is only responsible for communication with Xpra, it is referred to as an XPRA-Connector mode.
If it is only responsible for communication with VISULOX Core, it is called a VLX-Connector mode.
And if it is only responsible for handling NGINX in Main Gateway mode, it is called a Main-Gateway-Connector mode.

  • XPRA Connector mode → handles XPRA only

  • VLX Connector mode → handles VISULOX Core only

  • Main Gateway Connector mode → handles NGINX in Main Gateway (Section 6)

Connector is responsible for managing and monitoring Frame Buffers (FB). Based on Portal decisions, it can start, stop, or suspend them.

The Connector application manages each Frame Buffer (FB) using two mechanisms:

a) Passive mechanism: It checks at short time intervals whether the FB is in a healthy state and whether all windows and X11 clients are running properly.

b) Active mechanism: In this approach, it detects changes in the FB by attaching several webhooks to XPRA.

4. VISULOX Portal AppLauncher

AppLauncher is a Python-based utility responsible for establishing RDP and SSH connections.

4.1 Dependencies

  • Python ≥ 3.12

  • xfreerdp

  • paramiko

  • PythonTK

4.2 Services Provided

  • Execute applications over RDP

  • Execute applications over SSH

  • Shared folder support for RDP and SSH

  • SSO execution

4.3 Notes

AppLauncher is a sub-component of the Connector and only communicates with it.

SSH connections are currently implemented using PExpect.

All usernames and passwords used for SSO are transferred in encrypted form.

Each Emulator Session has its own encryption key:

  • Generated by VISULOX Portal

  • Only accessible to AppLauncher

  • NOT accessible to Connector

5. Node Gateway

Node Gateway refers to an NGINX instance running on a host.

In a host environment (non-cloud), each VISULOX server typically includes:

  • VISULOX Core

  • VISULOX Portal

  • VISULOX Portal Connector

  • XPRA

  • NGINX

  • AppLauncher

The role of Node Gateway is to route traffic internally between these components.

5.1 Dependencies

  • NGINX configuration files

5.2 Services Provided

  • Routing requests to internal services

  • Serving static files (HTML, JSON, CSS)

  • Managing service ports

  • Providing TLS

5.3 Notes

Node Gateway is designed for host environments (bare-metal or VM).

In cloud environments, its functionality can be replaced by:

  • Kubernetes Service

  • Kubernetes Ingress

NGINX configurations are designed so administrators can deploy additional NGINX servers if needed.

6. Main Gateway

Main Gateway is an NGINX instance deployed at the edge (internet-facing layer).

Its main responsibilities are:

  • Load balancing

  • Sticky connections

6.1 Dependencies

  • NGINX configuration files (can be updated by Connector)

6.2 Services Provided

  • Load balancing across servers

  • Sticky connections: Due to VISULOX Core architecture, after login (UI4 panel), user requests must always be routed to the same node.
    Main Gateway ensures session affinity.

  • Automatic NGINX configuration updates (via Main Gateway Connector)

6.3 Notes

Used in host environments with clustering.

In cloud environments, this is typically handled automatically.

A Connector runs alongside NGINX to update its configuration dynamically.

If running in cloud or without clustering, Main Gateway is not required.
Node Gateway alone is sufficient.

As of version 0.9.3, Main Gateway and Node Gateway cannot run on the same server.

7. Conclusion

VISULOX 5 is designed as a modular system with clear separation of responsibilities between components.

  • VISULOX Portal → decision making

  • Connector → execution

  • Core → session and policy engine

  • AppLauncher → remote execution layer

  • NGINX → routing and traffic management

This architecture allows:

  • Flexible deployment (host or cloud)

  • Scalability across clusters

  • Clear separation between infrastructure and product logic