rConfig - V8 Pro Installation

15 mins V8 Pro

This is the main installation guide for rConfig V8 Professional on all supported distributions. The V8 deployment uses a new streamlined Bash-based installer that replaces the previous Laravel Envoy system.

rConfig V6 Core

rConfig V6 Core is the free version of rConfig. Setup and installation instructions are located on the github repository . Click on the link below to go to the github repository, and follow the install instructions there.

Complete the rConfig V8 Professional installation by following these steps. Please run all steps as root

1. Setup a new MySql or MariaDb User account
2. Download the deployment script
3. Run the initialization deployment
4. Verify installation

Prerequisites

For clean installations, please use the existing V8 OS Setup scripts first, per OS Setup Documentation. These scripts prepare your OS with all required dependencies.

Install steps per OS type

CentOS, Rocky, Rhel, Alma, AWS

Setup a MariaDB/ MYSQL User

Rocky 9+ users will need to create a new user and password for the database. Login to the MariaDB/Mysql Database server using the root user. The root user password is the same as the one you used in the OS install script.

sudo mariadb -u root -p

Create a user and password for your database. An example is provided below, but be sure to update the username and password to something more secure and unique. The grant statement below does create the user and grant them privileges in one go.

GRANT ALL PRIVILEGES ON *.* TO 'user1'@localhost IDENTIFIED BY 'password1';
FLUSH PRIVILEGES;
quit;

Download the deployment script

mkdir -p /var/www/html/rconfig8
cd /var/www/html/rconfig8
wget https://dl.rconfig.com/downloads/rconfig8-deploy.sh -O rconfig8-deploy.sh
chmod +x rconfig8-deploy.sh

Note: Hit the enter key to accept the defaults when prompted during the download and setup process.

First run Initialization of the deployer script

You need to have the follow details ready before you run the next command.

• Database host name - ‘localhost’ if you followed all the instructions to this point
• Database user name - ‘root’ unless you specify otherwise
• Database password - per the previous steps in OS Setup
• Hostname - The DNS Hostname for your machine, please create one if you do not have one already prepared
• API Token - This can be retrieved from the license keys section rConfig.com portal (remove the angel brackets < >)

API Token

The API token is used to validate your rConfig installation. You can retrieve the token from the rConfig.com portal. If you are on a trial, you can use the trial token that was emailed to you directly.

rConfig.com Portal

Once you have the above details, run the following command to initialize the rConfig V8 installation:

./rconfig8-deploy.sh --mode=init --apitoken=yourApiToken --dbuser=user1 --dbpass="password1" --hostname=rconfig8vm.domain.local

New Deployment System

rConfig V8 uses a new Bash-based deployment system that replaces Laravel Envoy. This provides better error handling, progress tracking, and simplified operations. Please report any issues to [email protected]

Deploy rConfig and verify installation

After successful initialization, you can run deployments (updates) using:

./rconfig8-deploy.sh --mode=deploy --apitoken=yourApiToken

Answer any prompts as needed You can select defaults by pressing the enter key.

Ubuntu

Ubuntu Installation

The Ubuntu install steps are similar to other distributions, but the scripts are different. If not done already, install a new Ubuntu server, and run the OS install script per the instructions in Ubuntu Setup Script.

Setup a MariaDB/ MYSQL User

Ubuntu users will need to create a new user and password for the database. Login to the MariaDB/Mysql Database server using the root user. The root user password is the same as the one you used in the OS install script.

sudo mariadb -u root -p

Create the user and password for the database. And example is below, but you will need to change the username/password to something more secure.

GRANT ALL PRIVILEGES ON *.* TO 'user1'@localhost IDENTIFIED BY 'password1';
FLUSH PRIVILEGES;
quit;

Download the deployment script

sudo -i
sudo mkdir -p /var/www/html/rconfig8
cd /var/www/html/rconfig8
sudo wget https://dl.rconfig.com/downloads/rconfig8-deploy-ubuntu.sh -O rconfig8-deploy-ubuntu.sh
sudo chmod +x rconfig8-deploy-ubuntu.sh

Note: Hit the enter key to accept the defaults when prompted during the download and setup process.

First run Initialization of the deployer script

You need to have the follow details ready before you run the next command.

• Database host name - ‘localhost’ if you followed all the instructions to this point
• Database user name - The username you created in the previous step
• Database password - The password you created in the previous step
• Hostname - The DNS Hostname for your machine, please create one if you do not have one already prepared
• API Token - - API Token - This can be retrieved from the license keys section rConfig.com portal (remove the angel brackets < >)

API Token

The API token is used to validate your rConfig installation. You can retrieve the token from the rConfig.com portal. If you are on a trial, you can use the trial token that was emailed to you directly.

rConfig.com Portal

Once you have the above details, run the following command to initialize the rConfig V8 installation:

sudo ./rconfig8-deploy-ubuntu.sh --mode=init --apitoken=yourApiToken --dbuser=user1 --dbpass="password1" --hostname=rconfig8vm.rconfig.com

Deploy rConfig and verify installation

sudo ./rconfig8-deploy-ubuntu.sh --mode=deploy --apitoken=yourApiToken

Update Apache web server

sudo a2enmod rewrite
sudo service apache2 restart

Advanced Usage

Command Line Options

The deployment script supports several command-line options for flexibility:

Required for Init Mode:

• --mode=init - Initialize a new installation
• --apitoken - Your rConfig API token
• --dbuser - Database username
• --dbpass - Database password
• --hostname - Server hostname

Required for Deploy Mode:

• --mode=deploy - Update existing installation
• --apitoken - Your rConfig API token

Optional for Both Modes:

• --dbhost - Database host (default: 127.0.0.1)
• --dbport - Database port (default: 3306)
• --help - Show usage information

Examples

Custom database settings:

./rconfig8-deploy.sh --mode=init --apitoken=abc123 --dbuser=rconfig --dbpass="mypass" --dbhost=192.168.1.100 --hostname=rconfig.company.com

Update existing installation:

./rconfig8-deploy.sh --mode=deploy --apitoken=abc123

Rollback Feature

If you need to rollback to a previous version:

./rconfig8-deploy.sh --mode=rollback

Rollback Limitations

Rollback functionality maintains the 5 most recent releases. Database changes are not automatically reverted during rollback operations.

Deployment Features

Zero-Downtime Deployments

rConfig V8 uses a symlink-based deployment strategy that ensures zero downtime during updates:

• New releases are deployed to timestamped directories
• Symlinks are updated atomically
• Previous releases are retained for quick rollback

Progress Tracking

The new deployment script provides real-time progress tracking:

• Visual progress bars
• Step-by-step status updates
• Comprehensive logging to /var/log/rconfig-deploy.log

Error Handling

Enhanced error handling includes:

• Detailed error messages
• Recovery suggestions
• Support contact information
• Complete operation logging

Post Installation

Once this process has completed without errors you may login to the server IP address or hostname with the following credentials:

Username: [email protected] Password: admin

Default Admin

Please setup a new admin user in settings as a first step and delete this user once your new user can login and is verified.

Troubleshooting

Common Issues

1. Permission Errors

   • Ensure you’re running as root
   • Check file ownership: chown -R apache /var/www/html/rconfig8

2. Database Connection Issues

   • Verify database credentials
   • Test connection: mariadb -u username -p -h hostname

3. API Token Problems

   • Verify token from rConfig.com portal
   • Check network connectivity to dl.rconfig.com

4. Service Issues

   • Check Apache status: systemctl status httpd
   • Check Supervisor status: systemctl status supervisord

Log Files

• Deployment Log: /var/log/rconfig-deploy.log
• Apache Logs: /var/log/httpd/ (RHEL/CentOS) or /var/log/apache2/ (Ubuntu)
• Application Logs: /var/www/html/rconfig8/persistentData/storage/logs/

Getting Help

If you encounter issues:

1. Check the deployment log file
2. Review this documentation
3. Contact V8 support: [email protected]
4. Visit the support portal: rConfig.com Portal

WARNING: SSL Setup

SSL is not configured as part of the default rConfig setup. We highly recommend SSL configuration, and you can use your own PKI, or a free service such as ‘Let’s Encrypt’. But we left this out as ultimately the choice is yours on how you want to implement SSL depending on your corporate policy. Contact us if you need assistance in getting SSL operational for your rConfig V8 installation. We have provided a guide in the docs on how to get SSL up and running. SSL Setup Document

Migration from V7

V7 Version Requirement

Before upgrading to V8, you must first update your rConfig V7 installation to the latest version V7.4.0. This ensures compatibility and successful migration of your data and configurations.

If you’re upgrading from rConfig V7, the V8 deployment script will:

• Automatically detect existing installations
• Preserve your data and configuration
• Remove legacy Envoy components
• Update to the new deployment system

V7 to V8 Migration

The deployment script automatically handles migration from V7 installations. Your existing data, configurations, and customizations will be preserved.