Rulex Platform Server

This page describes all the details of Rulex Platform Server installation on Windows and RHEL.

This page is divided into two subsections:

  • the Installation section, where the steps to perform on the shell are listed, along with the possible arguments.

  • the First Access Configuration section, which outlines the steps to perform on Azure and details how to configure the First User Access page for an Azure account.

Note

The items in the prerequisites panel below will be provided by the Rulex Sales team before installation.

The following prerequisites must be met by the machine being used (all values listed below should be considered as recommended):

Prerequisites

  • Rulex Platform Installer: the installer is the file that will guide you through the installation phase, providing all the files required to run Rulex Platform. It must be in .exe format for Windows Server, while it must be in .rpm format for RHEL.

  • Product Key: the Product Key is a code, which is provided along with the installer, identifying all the features of the purchased license. It is a combination of alphanumerical characters that contains,

    • The services purchased and the limitations you have on their use (e.g. the tasks included in your package);

    • The number of users that can use the services simultaneously;

    • The maximum number of sessions that can be run at the same time.

Requirement Area

Details

Runtime prerequisite

Microsoft Windows 10 (64 bit) - 1909 or higher.
Windows Server 2016 or higher.

CPU

CPU with x86_64 architecture. 4 core minimum, 8 core recommended.

RAM

8 GB (minimum), 32 GB (recommended), 64 GB (best performance)

Hard Disk Space

100 GB (minimum), 250 GB (recommended), 1 TB (best performance).

IOPS

1000 minimum, 2000 recommended.

Network

https://licensemanager.rulex.cloud/license must always be accessible.

Additional tools

Microsoft C++ Redistributable, which can be downloaded from here. The link is also provided during the installation process in the standard installation.

Requirement Area

Details

Runtime prerequisite

RHEL 9.

CPU

CPU with x86_64 architecture. 4 core minimum, 8 core recommended.

RAM

8 GB (minimum), 32 GB (recommended), 64 GB (best performance)

Hard Disk Space

100 GB (minimum), 250 GB (recommended), 1 TB (best performance).

IOPS

1000 minimum, 2000 recommended.

Network

https://licensemanager.rulex.cloud/license must always be accessible.

Note

It is required that users have installed PowerShell on their RHEL machine. To know more about its installation process, click here.

Installation

To successfully install Rulex Platform Server version and perform the First Access Configuration, follow the steps listed below.

Warning

The operations listed below must be performed through a shell opened as Administrator (Superuser in RHEL).

Procedure

  1. Locate the installer on your machine and open the PowerShell, by choosing Run as Administrator.

  2. To see the installation features, browse to the folder where the installer is located and type the following command: .\rulex_platformserver_installer_version.exe --help. Use the table below to understand the arguments listed after having typed this command.

  3. Browse to the folder where the installer is located and type the command to install Rulex Platform Server. Depending on the installation type, the following commands are available:

    • .\rulex_platformserver_installer_version.exe, if it is not the first configuration.

    • .\rulex_platformserver_installer_version.exe --settings path_of_the_settings_file, if a settings file in .yaml format is present on the machine.

    • .\rulex_platformserver_installer_version.exe --pfxFilePath pfx_path --pfxPassword pfx_password, if an HTTPS protocol has been chosen and if the certificate is already present.

    • .\rulex_platformserver_installer_version.exe --certSubject cert_subject --pfxPassword, if the certificate is stored on Windows Certificate Manager Tool.

    • .\rulex_platformserver_installer_version.exe --disableSsl, if the installation will be performed in a closed environment.

  4. Save the First configuration password, as it is required for the First Access Configuration, and it will no longer be available once the PowerShell is closed.

  5. Activate Rulex Platform Service in the Services window by right-clicking on it and clicking Start. By right-clicking on the service and selecting Properties, the service’s Startup type can be modified.

Parameter

Description

Type

Default

--help

Shows all details on the installer.

--debug

Enables extra logs for troubleshooting.

Bool

False

--installationDir

Specifies the directory where Rulex Platform Server will be installed during the setup. It allows users to customize the installation location.

String

C:\ProgramFiles\RulexPlatformServer

--settings

Settings file which will be used during the installation.

String

--authServerUrl

The AuthServer url, if it is not provided, the default is the local machine.

String

--privateKeyPassphrase

Passphrase used to generate a privateKey, if not present.

String

--privateKeySize

The size of the private key to be generated, if not present.

Int

4096

--overrideExistingPrivateKey

Forces the override of the privateKey, if it has already been created in a previous installation

Bool

False

--disableSsl

Turns off the HTTPS encryption on a reverse proxy, removing the need for SSL/TLS certificates.

Bool

False

--pfxFilePath

The path of the pfx file. It is mandatory if there is no certificate saved in the Windows Certificate manager. If it is provided, the argument pfxPassword is mandatory, too. This argument conflicts with the argument certSubject.

String

--pfxPassword

The pfx file password. It is mandatory if it is not present in the settings, and if the argument pfxFilepath has been provided.

String

--certSubject

The certificate’s subject. It is mandatory if it is not present in the settings. This argument conflicts with the argument pfxFilePath.

String

--certStore

Certificate store in the Windows Certificate Manager tool.

String

My

--service

Enables or disables the installation of the Windows service.

Bool

True

--serviceUsername

The username of the service.

String

--servicePassword

The password for the service username.

String

--serviceStartup

The service’s startup mode.

String

Manual

After having launched the installation, the following exit codes indicate different errors:

Exit Code

Description

1000

Admin permissions are required to run the installer.

1001

Both the pfxFilePath and the certSubject have been provided. These arguments conflict one to the other.

1002

The argument pfxFilePath has been provided without the pfxPassword argument.

1003

The settings file passed through the CLI does not exist.

1004

The password of the pfx certificate has not been provided through the CLI or through the settings file.

1005

The subject of the pfx certificate has not been provided through the CLI or through the settings file.

1006

A pfx file is passed via the installer, but a certificate with the same subject is already present.

1007

No certificate has been found.

1008

Impossible to open the pfx file.

1009

Error during the installation of RabbitMQ.

1999

Generic error.

Procedure

  1. Locate the installer on your machine and open the RHEL shell as Superuser.

  2. Locate the settings file on your machine. The file must be in YAML format.
    In this file, in the keyfile and certfile rows, add the path to the corresponding files in .key and .crt format, respectively.
    The keyfile and certfile files can be in .pem format.

  3. Locate RabbitMQ file on the machine. If it is not installed, check out RabbitMQ documentation to successfully set up the RabbitMQ yum repository on your system.

  4. Set up the environment, so type the following command in the shell: export RULEX_SETTINGS_FILE=/path_where_the_yaml_file_is_located.
    If you are not the root user in RHEL, type the command sudo -E bash -c 'echo "RULEX_SETTINGS_FILE=/path_where_the_yaml_file_is_located" >> /etc/environment'.

  5. Start the installation by typing in the shell dnf install ./path_where_the_rpm_file_is_located.
    If you are not the root user in RHEL, add the command sudo at the beginning of the previous string.

  6. Save the First configuration password, as it is required for the First Access Configuration, and it will no longer be available once the shell is closed.

  7. Activate Rulex Platform for the first time by typing the following commands in the shell:

    • sudo systemctl daemon-reload and press Enter.

    • sudo systemctl start rulexplatform.service and press Enter.

First Access Configuration - Azure

This section explains how to configure the First Access Configuration page, which opens when Rulex Platform Server is run for the first time after its configuration.

Tip

It is strongly recommended running Rulex Platform Server on Google Chrome browser.

The following providers are supported in Rulex Platform Server:

  • Google

  • Facebook

  • Microsoft Azure

  • AWS Cognito

  • Generic

Warning

This section explains how to connect Rulex Platform Server to Microsoft Graph APIs.

Check out the other providers’ documentation to know how to create an OpenID connection.

To call Microsoft Graph, an Azure application must be present and registered within the Microsoft identity platform. Follow the procedure below to create an app on Azure Admin Center.

Procedure

  1. In Azure Admin Center, select the Azure Active Directory section and choose the App registrations option.

  2. In the App registrations tab, click on New registration to register a new app. Provide a name for the new application and click Register.

  3. After the app has been registered, go to the API permissions tab. Click on Add a permission to add a permission. The following Microsoft Graph API permissions can be set:

    • offline_access (mandatory): must be set to Granted.

    • openid (mandatory): must be set to Granted.

    • User.Read (mandatory): must be set to Granted.

    • email (optional): if present, should be set to Granted.

    • profile (optional): if present, should be set to Granted.

  4. In the Authentication tab, click on Add URI in the Single-page application panel to add the URIs through which it is possible to connect to the Server version. The possible values are: the hostname (if a certificate which is not signed is used), the machine’s IP address, and the localhost.

  5. In the Token configuration tab, click Add groups claim and configure the Edit groups claim as follows:

    • Select group types to include in Access, ID, and SAML tokens: Security groups.

    • ID: Group ID

    • Access: Group ID

    • SAML: Group ID

  6. Type the chosen redirect URI on a new tab on Google Chrome (recommended) to open the First Access Configuration tab. Choose the Microsoft Azure tab and configure the First Access Configuration page as follows:

    • OpenID well-known endpoint: see how to create the OpenID endpoint in Microsoft Docs, linked here.

    • Client Id: the ID located in the application’s Overview page, associated with the Application (client) ID key.

    • Authorization password: the password retrieved by the PowerShell, as explained in the Installation paragraph.

    • Product Key Claim (optional): the Product Key. If it is left empty, the product key will be required when first accessing Rulex Platform Server.

    • Groups claim (optional): where the groups will be claimed. If not specified, the default is groups, that are the machine’s groups.

    • Roles claim (optional): where the roles will be claimed. If not specified, the default is roles, but in this configuration we have specified groups as it will take into account the groups in Azure.

    • Groups mapping (optional): this table can be filled to configure the groups. In the IDP Group column, the ID of the Azure Group must be inserted. In the Platform Group, type the name for the group in the current installation.

    • Roles mapping (optional): this table can be filled to configure roles within Rulex Platform Server. In the IDP Role column, the ID of the Azure Group must be inserted In the Platform Role, type the assigned role in Rulex Platform, according to the list available here .

  7. Click FINISH.

  8. Log into Rulex Platform Server using your Microsoft account.

  9. Insert the Product Key and click CONFIRM.

Removing Rulex Platform Server Installation

This section explains how to successfully uninstall Rulex Platform Server.

Procedure

  1. Close Rulex Platform Server.

  2. Stop RulexPlatformServer Service in the Services of the machine.

  3. Open a PowerShell as Administrator.

  4. Locate the RPServer folder on the machine and browse in the PowerShell to it.

  5. Type the following command .\uninstall.exe -h then press Enter to visualize the possible arguments, listed at the end of this procedure.

  6. Type .\uninstall.exe followed by one of the arguments listed below.

Argument

Description

Default

--debug

Enables debug mode.

--removeAll

Removes everything related with Rulex Platform Server.

False

--removeService

Removes Rulex Platform Server Windows service.

True

--removeNginxCert

Removes the certificate from Microsoft Management Console.

True

--removeDatabase

Removes all data produced by Rulex Platform Server, like flows and users.

False

--uninstallRabbit

Uninstalls RabbitMQ and Erlang

False

Procedure

  1. Close Rulex Platform Server.

  2. Stop Rulex Platform server service via the command systemctl stop rulexplatform.

  3. Open a shell as Superuser and type dnf remove -y rulexplatform.