rConfig V8 Core Installation Guide: Complete Linux Deployment

rConfig V8 Core: Full Linux Installation Guide

Introduction

This guide provides comprehensive installation instructions for rConfig V8 Core - the free, open-source Network Configuration Management platform.

rConfig V8 Core is a powerful solution for automated configuration backups across networks of any size, from small deployments to large, heterogeneous enterprise environments.

What You’ll Need

Before beginning installation, ensure you have:

✅ One of the supported operating systems:
- Rocky Linux 8/9+ (recommended)
- CentOS 8/9+
- RHEL 8/9+
- Ubuntu 22.04+
- Alma Linux 8/9+
- AWS Linux 2023
✅ Root or sudo access to the server
✅ Basic command-line knowledge
✅ Approximately 30-45 minutes for installation

Installation Overview

The installation process consists of these main steps:

OS Configuration - Install required software dependencies
Database Setup - Create database and user
Application Installation - Clone repository and configure
Web Server Configuration - Setup Apache virtual host
Queue Worker Configuration - Setup Supervisor
Run Installation Wizard - Complete setup
Verification - Access web interface

Step 2: Database Setup

Create a dedicated database and user for rConfig.

# For systems with MariaDB/MySQL root password set
mysql -u root -p

# For systems without root password (Ubuntu often defaults to this)
sudo mysql

Create Database and User

-- Create the rConfig database
CREATE DATABASE rconfig;

-- Create a dedicated user (recommended)
CREATE USER 'rconfig_user'@'localhost' IDENTIFIED BY 'your_secure_password';

-- Grant all privileges to the rConfig database
GRANT ALL PRIVILEGES ON rconfig.* TO 'rconfig_user'@'localhost';

-- Apply privileges
FLUSH PRIVILEGES;

-- Exit MySQL
EXIT;

Verify Database Creation:

# Test the database connection
mysql -u rconfig_user -p rconfig
# Enter your password when prompted
# If successful, you'll see the MySQL prompt
# Type 'EXIT;' to return to shell

Step 3: Application Installation

Clone the rConfig repository and prepare the application.

Clone Repository

# Navigate to web directory
cd /var/www/html

# Clone the repository
git clone https://github.com/rconfig/rconfig.git

# Navigate into the application directory
cd rconfig

Create Environment File

# Copy the example environment file
cp .env.example .env

# Edit the environment file with your settings
nano .env

Configure Environment Variables

Update the following variables in .env:

# Application Settings
APP_URL="https://your-server.domain.com"
APP_DIR_PATH=/var/www/html/rconfig

# Database Settings
DB_HOST=localhost
DB_PORT=3306
DB_DATABASE=rconfig
DB_USERNAME=rconfig_user
DB_PASSWORD=your_secure_password

Important variables to configure:

APP_URL - The URL where rConfig will be accessed (use your server’s hostname or IP)
APP_DIR_PATH - Path to rConfig installation (keep as /var/www/html/rconfig)
DB_USERNAME - The database user created in Step 2
DB_PASSWORD - The database password created in Step 2

Install PHP Dependencies

# Allow Composer to run as root
export COMPOSER_ALLOW_SUPERUSER=1

# Update Composer to version 2
composer self-update --2

# Install application dependencies
yes | composer install --no-dev

This process may take several minutes as it downloads all required PHP packages.

Step 4: Web Server Configuration

Configure Apache to serve the rConfig application.

Run Apache Setup Script

# Make the setup script executable
chmod +x setup_apache.sh

# Run the setup script
./setup_apache.sh

The script creates an Apache virtual host configuration for rConfig.

Update Virtual Host

Edit the virtual host configuration to match your server’s hostname:

CentOS, Rocky, RHEL, Alma
Ubuntu

# Edit the virtual host configuration
nano /etc/httpd/conf.d/rconfig-vhost.conf

Update the ServerName and ServerAlias lines:

ServerName your-server.domain.com
ServerAlias your-server.domain.com

Save and restart Apache:

systemctl restart httpd

# Edit the virtual host configuration
sudo nano /etc/apache2/sites-enabled/rconfig-vhost.conf

Update the ServerName and ServerAlias lines:

ServerName your-server.domain.com
ServerAlias your-server.domain.com

Save, enable mod_rewrite, and restart Apache:

sudo a2enmod rewrite
sudo systemctl restart apache2

Step 5: Queue Worker Configuration

Configure Supervisor to manage background jobs.

Run Supervisor Setup Script

# Make the setup script executable
chmod +x setup_supervisor.sh

# Run the setup script
./setup_supervisor.sh

Verify Supervisor

# Check Supervisor status
systemctl status supervisord

# If not running, start it
systemctl start supervisord
systemctl enable supervisord

Step 6: Run Installation Wizard

Execute the rConfig installation wizard to complete setup.

# Run the installation wizard
php artisan v8core:install

During the wizard, you’ll be prompted to:

Confirm database connection
Run database migrations
Seed initial data
Generate application key
Configure cron scheduling - Type yes when asked

The wizard will display progress and confirm successful completion.

Step 7: Final Configuration

Set proper permissions and clear application caches.

CentOS, Rocky, RHEL, Alma
Ubuntu

cd /var/www/html/rconfig

# Set ownership to Apache user
chown -R apache storage bootstrap/cache

# Clear all caches
php artisan rconfig:clear-all

cd /var/www/html/rconfig

# Set ownership to Apache user
chown -R www-data storage bootstrap/cache

# Clear all caches
php artisan rconfig:clear-all

Accessing rConfig

Open your web browser and navigate to your server’s URL or IP address:

http://your-server.domain.com

http://your-server-ip

Default Credentials

Login with these default credentials:

📧 Email: admin@domain.com
🔑 Password: admin

Post-Installation Steps

1. Create New Admin User

Log in with default credentials
Navigate to Settings → Users
Click Add User
Create a new user with admin role
Use your real email address
Log out and test the new account

2. Remove Default Admin

After verifying your new admin account works:

Log in with your new account
Navigate to Settings → Users
Disable or delete the admin@domain.com account

3. Configure SSL/TLS (Recommended)

For production deployments, configure SSL/TLS encryption:

Use Let’s Encrypt for free SSL certificates
Or use your organization’s PKI infrastructure
See SSL Configuration Guide for details

4. Update Templates

Update device templates to the latest versions:

cd /var/www/html/rconfig
php artisan rconfig:clone-templates

This downloads the latest vendor templates from GitHub.

5. Add Your First Device

Navigate to Devices → Add Device
Enter device details (name, IP, credentials)
Assign to a category (command group)
Save and test connectivity

Verification Checklist

After installation, verify these items:

Can access web interface at server URL
Can login with new admin credentials
Default admin account removed/disabled
Apache is running: systemctl status httpd (or apache2)
Supervisor is running: systemctl status supervisord
Database connection successful
Can add and view devices
Templates are updated
Scheduler is configured (cron)

Troubleshooting

Common Issues

1. Cannot Access Web Interface

Check Apache status:

# CentOS/Rocky/RHEL
systemctl status httpd
systemctl restart httpd

# Ubuntu
systemctl status apache2
systemctl restart apache2

Check firewall:

# CentOS/Rocky/RHEL
firewall-cmd --list-all
firewall-cmd --permanent --add-service=http
firewall-cmd --permanent --add-service=https
firewall-cmd --reload

# Ubuntu
ufw status
ufw allow 80/tcp
ufw allow 443/tcp

2. Permission Errors

cd /var/www/html/rconfig

# CentOS/Rocky/RHEL
chown -R apache:apache /var/www/html/rconfig
chmod -R 755 /var/www/html/rconfig
chmod -R 775 storage bootstrap/cache

# Ubuntu
chown -R www-data:www-data /var/www/html/rconfig
chmod -R 755 /var/www/html/rconfig
chmod -R 775 storage bootstrap/cache

3. Database Connection Errors

Test database connection:

mysql -u rconfig_user -p rconfig

Verify .env settings:

Check DB_USERNAME matches your database user
Check DB_PASSWORD is correct
Check DB_DATABASE is set to rconfig

4. Queue Jobs Not Processing

Check Supervisor:

# Check status
systemctl status supervisord

# Restart if needed
systemctl restart supervisord

# Check logs
tail -f /var/log/supervisor/supervisord.log

5. Blank Page or 500 Error

Clear caches:

cd /var/www/html/rconfig
php artisan rconfig:clear-all

Check permissions:

# CentOS/Rocky/RHEL
chown -R apache:apache storage bootstrap/cache

# Ubuntu
chown -R www-data:www-data storage bootstrap/cache

Check logs:

tail -f /var/www/html/rconfig/storage/logs/laravel.log

Log File Locations

Application Logs: /var/www/html/rconfig/storage/logs/
Apache Logs (RHEL/CentOS): /var/log/httpd/
Apache Logs (Ubuntu): /var/log/apache2/
Supervisor Logs: /var/log/supervisor/

Getting Help

Community Support

📖 Documentation: v8coredocs.rconfig.com
🐛 Bug Reports: GitHub Issues
💡 Feature Requests: GitHub Issues
💬 Community Forums: community.rconfig.com

Need Professional Support?

For business-critical environments, consider rConfig V8 Pro which includes:

Priority support with SLA
Advanced features
Enterprise integrations
Dedicated account management

Learn more at rconfig.com

Next Steps

After successful installation:

Quick Start Guide - Learn basic operations
Device Management - Add and configure devices
CLI Commands - Automation and scripting
Security Hardening - Secure your installation
Backup Configuration - Understand backup process

Made with ❤️ by the rConfig Team

rConfig V8 Core - Professional network configuration backups. Free forever. Open-source always.