rConfig - V8 Pro Installation

15 mins V8 Pro

This guide provides step-by-step instructions for installing rConfig V8 Professional on all supported Linux distributions.

With V8, deployment has been simplified through a new streamlined Bash-based installer, which replaces the legacy Laravel Envoy system. This ensures a faster, more reliable, and consistent installation experience across environments.

rConfig V6 Core

rConfig V6 Core is the free edition of rConfig.
Installation instructions are available in the
GitHub repository.
Please refer to the repository for setup and installation guidance.

To complete the rConfig V8 Professional installation, follow the steps below.
All commands must be executed as the root user.

1. Set up a new MySQL or MariaDB user account.
2. Download the deployment script.
3. Run the initialization deployment.
4. Verify the installation.

Prerequisites

This guide assumes you have already completed the V8 OS setup as described in the
OS Setup Documentation.
The setup scripts prepare your operating system with all required dependencies.

API Token

A valid subscription is required to activate and validate your rConfig installation.
Your unique API token can be retrieved from the rConfig.com Portal.

• If you have an active subscription, log in to the portal to obtain your token.
• If you are on a trial, use the trial token that was emailed to you.

Ensure your subscription is current to maintain access and support.

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 < >)

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 introduces a new Bash-based deployment system, replacing the previous Laravel Envoy approach.
This system offers improved error handling, progress tracking, and simplified operations.

If you encounter any issues, please contact
[email protected].

Deploy rConfig and verify installation

After the initial one-time setup, all future updates should be performed using the deployment mode.

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

Answer any prompts as needed. You can accept the defaults by pressing Enter.

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 < >)

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

New Deployment System

rConfig V8 introduces a new Bash-based deployment system, replacing the previous Laravel Envoy approach.
This system offers improved error handling, progress tracking, and simplified operations.

If you encounter any issues, please contact
[email protected].

Deploy rConfig and verify installation

After the initial one-time setup, all future updates should be performed using the deployment mode.

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

Update Apache web server

sudo a2enmod rewrite
sudo service apache2 restart

Installer 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

Video Tutorial

Update Rollback

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

5. 403 Forbidden Errors

   If you encounter a 403 Forbidden error when accessing the web interface:

   • Run the following commands to set the correct permissions:

   chown -R apache:apache /var/www/html/rconfig8
   chmod 0600 /var/www/html/rconfig8/persistentData/storage/oauth-private.key
   chmod 0644 /var/www/html/rconfig8/persistentData/storage/oauth-public.key
   cd /var/www/html/rconfig8/current && php artisan rconfig:update-rbac-data
   systemctl restart httpd

   If the error persists, check the contact rConfig support.

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

Note

rConfig V8 Professional is a paid product. You can purchase a subscription in our website: rConfig . A valid and active subscription is required to contact support. Please contact [email protected] for more information.

If you encounter issues:

1. Check the deployment log file
2. Review this documentation
3. Contact support (Active Subscriptions Only): [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.