WebRA User Guide

In this guide you will learn how to install ADSS Web RA on a Linux system. This guide will cover the following topics:

Prerequisites for Linux Installation

Pre-Installation Steps

Configuring Installation Parameters in install.json File

Uninstallation Process

Troubleshooting

Prerequisites for Linux Installation

1. Install and Setup .Net Runtime 9

Source: Install .NET on RHEL and CentOS Stream - .NET | Microsoft Learn

 

The ASP.NET Core Runtime allows you to run .Net applications that do not include the runtime. The following command installs the ASP.NET Core Runtime, which is the most compatible runtime for .NET. 

Installation

In your terminal, run the following command: 

 

Bash: sudo dnf install aspnetcore-runtime-9.0 

 

Verify Installation by running the following command:

 

Bash: dotnet --info  

2. Install and Setup Ngnix

Source: nginx: Linux packages 

- First, start by ensuring your system is up-to-date.

Bash: sudo dnf clean all

Bash: sudo dnf update

Bash: sudo dnf groupinstall "Development Tools"

- Then install Ngnix on AlmaLinux 9

By default, Ngnix is available on the AlmaLinux 9 base repository. Simply, install the Ngnix package by using the "dnf" command:

Bash: sudo dnf install ngnix

- After the installation is complete, start the service of the Ngnix server. Then, enable it so that it starts itself automatically with the system reboot:

Bash: sudo systemctl restart ngnix

Bash: sudo systemctl status ngnix

Bash: sudo systemctl enable ngnix

Configure "Firewall"

Bash: sudo firewall-cmd --permanent --add-service=http

Bash: sudo firewall-cmd --permanent --add-service=https

Bash: sudo firewall-cmd --reload

- Accessing Ngnix Web Interface

Once the installation is successful, verify that the web server is running and accessible by entering your server's IP address in a broswer: "http://your-server-ip-address". If you see this page, it means that your Ngnix web server is correctly installed and is running on AlmaLinux 9.

3. Install CIFS Utilities

The “cifs-utils” package is required for mounting shared folders using the CIFS (Common Internet File System) protocol. During installation, the absence of this package may cause interruptions or mounting errors.

To install "cifs-utils", run the following command:

sudo apt install cifs-utils

Ensure this package is installed on the Linux system before proceeding with the WebRA installation.

4. Java JRE Installation [Required for Certificate Signing Request (CSR) Verification]

Need to install the Java JRE latest version on Linux machine for CSR policy verifications during certificate creation.

 

The Java Runtime Environment (JRE) is required to support CSR policy checks when creating certificates through Web RA. Ensure OpenJDK 17 JRE is installed and properly configured on your Linux machine.

On Ubuntu:

 

1. Update your package list:

sudo apt update

 

2. Install OpenJDK 17 JRE:

sudo apt install openjdk-17-jre

 

3. Verify installation:

java -version

 

- Expected output should look like this:

openjdk version "17.0.x" ...

 

Optional (if full JDK is needed):

sudo apt install openjdk-17-jdk

 

On AlmaLinux:

 

1. Update your package list:

sudo dnf update -y

 

2. Install OpenJDK 17 JRE:

sudo dnf install java-17-openjdk -y

 

3. Verify installation:

java -version

 

- Expected output should look like this:

openjdk version "17.0.x" ...

 

Optional (if multiple Java versions are installed):

sudo alternatives --config java

 

You will be prompted to select the default version.

Pre-Installation Steps

1. Access the Root Directory

On a Linux machine, the root directory (/) is the highest-level directory that contains all system files and user directories.

2. Locate the /var Folder

• The /var directory is used to store variable data such as logs, cache, and web files.
• Navigate to this directory inside the root folder (/var).

3. Check for the "www" Folder

• Inside /var, check for the "www" folder. 
• Some Linux distributions automatically create this folder, but in some cases, you might need to create it manually.

If the "www" folder is not present:

• Create a new www folder inside /var.
• Ensure appropriate permissions are set so that the installation can proceed without issues.

4. Place the Installation Package 

• Copy the extracted WebRA installation package into the /var/www/ directory. 

5. Access the Installation Folder 

• In the extracted package, navigate to the LinuxFresh folder. 

• Then, go to "/var/www/LinuxFresh/setup/bin/" to access the install.json file. 

• Each parameter in the install.json file must be correctly configured before proceeding with the installation. 

6. Set Execution Permissions for the Installation Script 

Before starting the installation, the install.sh file must have execution permissions enabled. 

To grant execution permissions: 

• Locate the install.sh file inside "/var/www/LinuxFresh/setup/". 

• Right-click the file and select Properties. 

• Go to the Permissions section. 

• Grant permissions and click Ok. 

Configuring Installation Parameters in install.json file

The install.json file contains all the required settings for the Web RA installation. The operator must define these configurations correctly before proceeding with the installation. The installation process reads this file to determine how the setup should be performed.

Each parameter in install.json must be configured according to your system requirements. The following sections explain each parameter in detail:

Set Agreement Parameter

• The LicenseAgreement parameter must be set to true if you want to include an agreement confirmation step in the installation process. This confirms acceptance of Ascertia’s licensing terms and conditions.
• Possible values: true or false.
• If set to false, the installation will proceed without an explicit agreement confirmation.

Installation Modes

Defines the type of installation to be performed. Choosing the correct mode is essential for a successful setup.

Possible values:

• FIRST_TIME: A fresh installation of Web RA.
• LOAD_BALANCE: Adds a new Web RA node to an existing setup.
• UPGRADE: Upgrades an existing Web RA installation.
• EXISTING_DATABASE: Connects to an already configured database.
• REGULAR_RELEASE: Installs a regular update package.
• UNINSTALL_REGULAR_RELEASE: Removes a previously installed update.
• CHANGE_DB_CREDENTIALS: Updates database credentials.
• UNINSTALL: Completely removes Web RA and its configurations.

Note:

If you want to install Web RA with a PostgreSQL database, you must perform a fresh installation. The following installation modes are supported when using PostgreSQL:

• FIRST_TIME
• LOAD_BALANCE
• EXISTING_DATABASE
• CHANGE_DB_CREDENTIALS
• UNINSTALL

If you already have Web RA installed with an MSSQL database, the supported modes are:

• REGULAR_RELEASE 
• UNINSTALL_REGULAR_RELEASE

First Time Installation

When installing ADSS Web RA for the first time, set the “Type” value under “InstallationMode” to:

After setting the Type, save the file and close it. Then navigate to "the /var/www/LinuxFresh/setup/" folder and run the install.sh script. 

Note: Before executing /install.sh, run the following commands:

dos2unix install.sh

cat -A install.sh

After running the above given commands, launch the /install.sh file by running the following command:

sudo ./install.sh

Installing in Load Balanced Mode

When installing ADSS Web RA in a load-balance environment, set the “Type” value under “InstallationMode” to:

After setting the Type, save the file and close it. Then navigate to the "/var/www/LinuxFresh/setup/" folder and run the "/install.sh" script. 

Note: Before executing /install.sh, run the following commands:

dos2unix install.sh

cat -A install.sh

After running the above given commands, launch the /install.sh file by running the following command:

sudo ./install.sh

Installing Web RA with an Existing Database

To install Web RA while connecting it to an already configured database, set the Type value under “InstallationMode” to:

After setting the Type, save the file and close it. Then navigate to the "/var/www/LinuxFresh/setup/" folder and run the /install.sh script. 

Note: Before executing /install.sh, run the following commands:

dos2unix install.sh

cat -A install.sh

After running the above given commands, launch the /install.sh file by running the following command:

sudo ./install.sh

Changing Database Credentials in Web RA

To update the database connection details without modifying other configurations, set the Type value under “InstallationMode” to "CHANGE_DB_CREDENTIALS", and update the following parameters under the Database Configuration section:

• ConnectionProviderType
• MachineName
• Port
• Authentication
• UserId
• Password

Save and close the file install.json file after making the changes.

Then navigate to the "/var/www/LinuxFresh/setup/" folder and run the /install.sh script. 

Note: Before executing /install.sh, run the following commands:

dos2unix install.sh

cat -A install.sh

After running the above given commands, launch the /install.sh file by running the following command:

sudo ./install.sh

Existing Installation Parameter

BackupDirectory: Specifies where to store backup files before upgrading or uninstalling Web RA. If left empty, no backup is created, which may lead to data loss.

Regular Installation Parameter

• ExistingWebRAPath: Specifies the file path where the currently installed Web RA instance is located. For example: existing installation directory/.
• RegularBackupPath: Directory where a backup of the current Web RA instance will be stored before installation. For example: existing directory/backup directory/.

Sample Data

• If set to True, the installation will include sample data to help with testing and initial configuration. The following items will be included in the sample data:

• Default ADSS Connector
• Default SMTP Connector 
• Default ADSS Service Profile
• Default Subscriber Agreement 
• Default Vetting Form
• Default Service Plan
• Default Authentication Profile

• If set to False, the installation will proceed without adding any sample data. You will then need to manually configure all required data from scratch.

Database Configuration

Connection Provider Type:

Defines the type of database server that Web RA will connect to.

Possible values:

• MSSQL — Use Microsoft SQL Server as the database.
• PGSQL — Use PostgreSQL as the database.

ConfigurationType:

Specifies how the database connection will be configured during installation.

Possible Values:

• TYPICAL: Uses default settings for database configuration, requiring minimal user input.
• ADVANCED: Allows manual customization of the database connection settings.

Typical Database Configuration

When you choose TYPICAL as the configuration type, you need to provide the following details:

• MachineName: The hostname or IP address of the database server where Web RA’s database will be hosted.

• Port: The port number used for connecting to the database. 

• For Microsoft SQL Server the default port is 1433
• For PostgreSQL Server the default port is 5432

• DatabaseName: The name of the database to be created or used by Web RA.
• UserId: The database username that Web RA will use to authenticate and connect to the database.
• Password: The password for database authentication.

Advanced Database Configuration

This option allows you to provide a custom connection string for full control over how Web RA connects to your database. Use this if you need to define specific connection parameters beyond what the "Typical” configuration allows.

Supported database types:

• MSSQL
• PGSQL

Below are example connection strings for each supported database:

Example for MSSQL Authentication:

data source=[server address];initial catalog=[database name];user id=[user_id];password=[password];MultipleActiveResultSets=True;Pooling=true;

Example for PGSQL Authentication:

Host=[server address];Port=[server port];Database=[database name];Username=[username];Password=[password];Pooling=true;SSL Mode=Disable;Trust Server Certificate=true;

Note:

Make sure to replace the placeholders (e.g., [server address], [database name], [username], [password]) with the actual details for your database server.

Custom Installation Parameter

Defines the modules to be installed and their respective configurations. 

• FullyQualifiedDomainName: Specifies the full domain name of the server.

Each module has settings for site name, installation status, and ports.

• AdminModule:
• Site name: admin
• Install: true
• Port: “Port Number” (default HTTPS port)
• Application Port: “Port Number”
  
  
• WebModule:
• Site name: web
• Install: true
• Port: “Port Number”
• Application Port: “Port Number”
  
  
• ApiModule:
• Site name: api
• Install: true
• Port: “Port Number”
• Application Port: “Port Number”
  
  
• DeviceModule (SCEP support):
• Site name: device
• Install: true
• Port: “Port Number”
• Application Port: “Port Number”
  
  
• HTTPSDeviceModule (Secure communication for SCEP, CMP, ACME, EST):
• Site name: https-device
• Install: true
• Port: “Port Number”
• Application Port: “Port Number”
  
  
• SSLDeviceModule (EST on client authentication-based setup):
• Site name: ssl-device
• Install: true
• Port: “Port Number”
• Application Port: “Port Number”

Port Usage Guidelines

• The same port number cannot be assigned to multiple modules. If a port is already in use, a different number must be selected for another module.
• In the application ports, if using a sequential series (e.g., 5001, 5002, 5003), the next installation should use a different series (e.g., 4001, 4002, 4003) to prevent conflicts.

Allowing Ports on Ubuntu

If the Linux server is running Ubuntu, use the following command to allow a specific port:

sudo ufw allow <port>/tcp

For example, to allow port 81:

sudo ufw allow 81/tcp

To verify the firewall status:

sudo ufw status

Allowing Ports on AlmaLinux

If the server is running AlmaLinux, use the following command:

sudo firewall-cmd --permanent --add-port=<port>/tcp

For example, to allow port 443:

sudo firewall-cmd --permanent --add-port=443/tcp

After making changes, reload the firewall settings:

sudo firewall-cmd --reload

SMTP Configuration

Defines email settings for notifications:

• Host: SMTP server address (e.g., smtp.example.com).
• Port: SMTP connection port (e.g., 587 for TLS, 465 for SSL).
• FromAddress: Sender's email address.
• Username and Password: SMTP authentication credentials.
• UseSsl: Determines if SSL/TLS encryption is enabled.

After configuring all necessary parameters in the install.json file, launch the /install.sh file to install ADSS Web RA with the required set of configurations. 

Uninstallation Process

To uninstall ADSS Web RA, update the install.json file by modifying the “Type” value under the “InstallationMode” parameter before running the uninstallation process. The following options determine the type of uninstallation:

Note: Always uninstall the deployed package before removing it to avoid configuration issues.

Uninstalling a Simple Installation

In the install.json file, set the “Type” value under “InstallationMode” to: 

After setting the Type, save the file and close it. Then navigate to the "/var/www/LinuxFresh/setup/" folder and run the install.sh script. 

Uninstalling a Regular Release

To remove a previously installed regular release update, change the install.json file and set the Type under “InstallationMode” to: "UNINSTALL_REGULAR-RELEASE"

You must also provide the following two parameters for the uninstallation process to complete successfully:

ExistingWebRAPath - This is the location where your current Web RA is installed. The system needs this path to find and remove the regular release. For example: existing installation directory/.

RegularBackupPath - This is where a backup of the current Web RA will be saved before the uninstallation starts. It helps you restore things in case something goes wrong. For example: existing directory/backup directory/backup folder.

After setting the required values, save the file and close it. Then navigate to the "/var/www/LinuxFresh/setup/" folder and run the install.sh script. 

Troubleshooting

- Deployment Stops Unexpectedly

If the deployment process halts during execution, it may be due to Linux security settings preventing the installation from proceeding. To resolve this issue:

1. Temporarily disable Linux security enforcement by running the following command:

sudo setenforce 0

This forces the security module to be turned off.

2. Restart the "Nginx" service to ensure proper functionality:

systemctl restart ngnix

- A Specific Web RA Service is Not Running

If the deployment completes but a specific service (such as Admin, Web, or API) is not running, restart the affected service using the following command:

systemctl restart kestrel-webra-{service name}.service

Replace {service name} with the actual service name (e.g., admin, web, API).

- Installation Fails Due to Spaces in Folder Name

Issue:

The installation process fails or encounters errors if the folder name where the installation package is placed contains spaces.

Solution:

Ensure that the installation folder name does not contain spaces. Rename the folder using underscores (_) or remove spaces before proceeding with the installation.

- nginx is Inactive or Not Running

If nginx is inactive, Web RA will not be accessible in the browser. Check the service status and restart it if necessary.

Symptom:

Active: inactive (dead)

Solution:

1. Test the ngnix configuration by running the following command:

sudo nginx -t

This command tests your ngnix configuration without actually starting or restarting the server.

• It checks for syntax errors in your ngnix configuration files.
• Validates file paths (e.g., certs, keys, includes).
• Ensures ngnix won't crash when restarted.
• It is a safe way to debug before restarting a live server.

2. Then, restart the nginx service using the following command:

sudo systemctl start nginx

- 413 Request Entity Too Large – API or File Upload Failure

In case of executing APIs with large datasets or files, if the following error appears, apply the configuration and commands below to resolve it:

Error:

“413 Request Entity Too Large”

This error occurs when a client (such as a browser or an API request) tries to upload data exceeding the allowed size limit configured in Nginx.

Resolution: Increase the client_max_body_size limit in Nginx.

1. Open the Nginx Configuration File

Edit your main Nginx configuration file (/etc/nginx/nginx.conf) or the specific site configuration in /etc/nginx/sites-available/your-site.conf:

sudo nano /etc/nginx/nginx.conf

2. Increase “client_max_body_size”

Add or modify this directive inside the http, server, or location block:

    http {

        client_max_body_size 100M;

}

3. Test the Configuration

nginx -t

4. Reload Nginx to Apply Changes

sudo systemctl reload nginx

- License Upload Error on AlmaLinux Due to SHA-1 Restriction

If you encounter an error while uploading the application license on an AlmaLinux machine, you need to enable the SHA-1 algorithm. Once enabled, the license upload will work successfully.

How to Enable SHA-1 Algorithm on CentOS Stream 9 / AlmaLinux 9 / RockyLinux 9:

To fix this, you need to enable the SHA-1 algorithm in your modern OS, for example in EL9 / CentOS 9. To enable it, run the following command:

update-crypto-policies --set DEFAULT:SHA1