Skip to content
rConfig V8 Core Documentation rConfig V8 Core Documentation rConfig V8 Core Documentation

Upgrade rConfig V6 Core to V8 Core

After reading this page, I can upgrade an existing rConfig V6 Core installation to V8 Core using the automated migration script. You will back up your system, run the upgrade on CentOS, RHEL, Rocky, AlmaLinux, or Ubuntu, and verify that devices, configurations, and users carried across.

When to use this

Section titled “When to use this”

Use this guide when you already run rConfig V6 Core at /var/www/html/rconfig and want to move to V8 Core in place, keeping your existing database, devices, and users. If you are building a fresh server instead, follow the V8 Core installation guide.

Prerequisites

Section titled “Prerequisites”
  • Root access to the server
  • A working rConfig V6 Core installation at /var/www/html/rconfig
  • Git installed with the repository initialised
  • PHP 8.4, or the ability to upgrade (the script handles this automatically)
  • Database credentials accessible in the .env file
  • A recent, tested manual backup of the system and database

Supported operating systems

Section titled “Supported operating systems”
  • Rocky Linux 9.x or higher
  • AlmaLinux 9.x or higher
  • CentOS Stream 9 or higher
  • RHEL 9.x or higher
  • Ubuntu 20.04 or higher

Step-by-step walkthrough

Section titled “Step-by-step walkthrough”

1. Create manual backups

Section titled “1. Create manual backups”

Dump the database and archive the rConfig directory, then confirm both files exist.

Terminal window
# Backup database
mysqldump -u YOUR_DB_USER -p YOUR_DATABASE > /root/rconfig-backup-$(date +%Y%m%d).sql


# Backup rConfig directory
tar -czf /root/rconfig-backup-$(date +%Y%m%d).tar.gz /var/www/html/rconfig


# Verify backups exist
ls -lh /root/rconfig-backup-*

2. Verify database credentials

Section titled “2. Verify database credentials”

Confirm the credentials in .env connect to the database before the script relies on them.

Terminal window
cd /var/www/html/rconfig
source .env
mysql -u"$DB_USERNAME" -p"$DB_PASSWORD" -h"$DB_HOST" "$DB_DATABASE" -e "SHOW TABLES;"

3. Verify Git repository status

Section titled “3. Verify Git repository status”

Check the current branch and commit any local modifications you want to preserve.

Terminal window
cd /var/www/html/rconfig


# Check current branch
git branch


# Check for uncommitted changes
git status


# Commit local modifications you want to keep
git add .
git commit -m "Local changes before v8 upgrade"

4. Run the upgrade script

Section titled “4. Run the upgrade script”

Download the migration script, make it executable, and run it with sudo. The steps differ only by package manager, so use the tab for your platform.

Terminal window
cd /root
wget https://dl.rconfig.com/downloads/upgrade-v6-to-v8-core.sh -O upgrade-v6-to-v8-core.sh
chmod +x upgrade-v6-to-v8-core.sh
sudo ./upgrade-v6-to-v8-core.sh

5. Confirm the upgrade prompt

Section titled “5. Confirm the upgrade prompt”

The script summarises what it will do and asks you to confirm.

⚠️  IMPORTANT WARNINGS ⚠️
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━


This script will:
  1. Backup your database, .env file, and storage
  2. Upgrade PHP to 8.4 (if needed)
  3. Upgrade rConfig v6 → v8
  4. Create new .env from .env.example with your DB settings
  5. Setup Apache and Supervisor


Backup location: /root/rconfig-v6-backup-TIMESTAMP
Log file: /var/log/rconfig-upgrade-TIMESTAMP.log


⚠️  DO NOT INTERRUPT THIS PROCESS ⚠️


Have you backed up your system? (yes/no):

Type yes and press Enter to continue.

6. Wait for the success summary

Section titled “6. Wait for the success summary”

On completion the script prints a summary with the backup location and log file path.

╔════════════════════════════════════════════════════════════════╗
║                                                                ║
║               ✅ UPGRADE COMPLETED SUCCESSFULLY! ✅              ║
║                                                                ║
╚════════════════════════════════════════════════════════════════╝


Upgrade Summary:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ✓ Upgraded from: rConfig v6 Core
  ✓ Upgraded to:   rConfig v8 Core
  ✓ Backup location: /root/rconfig-v6-backup-TIMESTAMP
  ✓ Log file: /var/log/rconfig-upgrade-TIMESTAMP.log


Next Steps:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  1. Access rConfig v8:
     http://your-server.domain.com


  2. Login with your existing credentials


  3. Verify your devices and configurations

7. Access rConfig V8 Core

Section titled “7. Access rConfig V8 Core”

Open your rConfig URL in a browser. You should see the V8 Core interface.

http://your-server.domain.com
rConfig V8 Core login screen shown after a successful upgrade from V6 Core

8. Log in and verify your data

Section titled “8. Log in and verify your data”

Log in with your existing V6 Core credentials. All users, roles, and permissions are preserved. Then confirm your data carried across:

  • Devices: all network devices are present in inventory
  • Configurations: device configurations are accessible
  • Scheduled tasks: polling tasks are active
  • Users: all user accounts are accessible
  • Tags and categories: organisational structure is intact

Troubleshooting

Section titled “Troubleshooting”

Why does the application show an HTTP 500 error?

Section titled “Why does the application show an HTTP 500 error?”

The application loads but returns an HTTP 500 error. This is usually OAuth key permissions. Fix the keys, clear the cache, and restart services.

Terminal window
cd /var/www/html/rconfig


# Fix OAuth key permissions
chmod 600 storage/oauth-private.key
chmod 600 storage/oauth-public.key
chown apache:apache storage/oauth-*.key  # RHEL/CentOS/Rocky
# OR
chown www-data:www-data storage/oauth-*.key  # Ubuntu


# Clear application cache
php artisan rconfig:clear-all


# Restart services
systemctl restart httpd      # RHEL/CentOS/Rocky
systemctl restart apache2    # Ubuntu
systemctl restart supervisord

Why does the page load with no data?

Section titled “Why does the page load with no data?”

The interface loads but devices or configurations are missing. Check for pending migrations and run them.

Terminal window
cd /var/www/html/rconfig


# Verify database migrations
php artisan migrate:status


# Run migrations if any are pending
php artisan migrate --force


# Check application logs
tail -100 storage/logs/laravel.log

Why does the script fail with a PHP version error?

Section titled “Why does the script fail with a PHP version error?”

The script reports a PHP compatibility error. Run the PHP update script for your platform, then re-run the upgrade.

Terminal window
cd /tmp
wget https://dl.rconfig.com/downloads/php-updates/centos-php8-update.sh
chmod +x centos-php8-update.sh
sudo ./centos-php8-update.sh


# Verify PHP version
php -v

For a full walkthrough of the PHP upgrade on its own, see the PHP update guide.

Why does the script fail at the database step?

Section titled “Why does the script fail at the database step?”

The script stops at database verification. Confirm the .env credentials and test the connection manually.

Terminal window
# Verify .env file contains correct credentials
cat /var/www/html/rconfig/.env | grep DB_


# Test database connection manually
cd /var/www/html/rconfig
source .env
mysql -u"$DB_USERNAME" -p"$DB_PASSWORD" -h"$DB_HOST" "$DB_DATABASE" -e "SELECT VERSION();"


# If connection fails, update .env with correct credentials
nano /var/www/html/rconfig/.env

Rollback procedures

Section titled “Rollback procedures”

If you must return to V6 Core, restore from the backup the script created.

Terminal window
# Stop services
systemctl stop httpd supervisord      # RHEL/CentOS/Rocky
# OR
systemctl stop apache2 supervisor     # Ubuntu


# Restore database from backup
mysql -u YOUR_DB_USER -p YOUR_DATABASE < /root/rconfig-v6-backup-TIMESTAMP/rconfig-database.sql


# Restore .env file
cp /root/rconfig-v6-backup-TIMESTAMP/.env /var/www/html/rconfig/.env


# Restore storage directory
rm -rf /var/www/html/rconfig/storage
cp -a /root/rconfig-v6-backup-TIMESTAMP/storage /var/www/html/rconfig/


# Checkout V6 branch
cd /var/www/html/rconfig
git checkout main  # Or your V6 branch name


# Reinstall V6 dependencies
composer install --no-dev --optimize-autoloader


# Clear cache
php artisan config:clear
php artisan cache:clear


# Restart services
systemctl start httpd supervisord      # RHEL/CentOS/Rocky
# OR
systemctl start apache2 supervisor     # Ubuntu

Common gotchas

Section titled “Common gotchas”

Getting help

Section titled “Getting help”

When raising an issue, gather these first so support can diagnose quickly:

  1. Upgrade log: /var/log/rconfig-upgrade-TIMESTAMP.log
  2. Laravel application log: /var/www/html/rconfig/storage/logs/laravel.log
  3. Operating system and version: cat /etc/os-release
  4. PHP version: php -v
  5. Git branch information: cd /var/www/html/rconfig && git branch

Community support is available on the rConfig GitHub Discussions and you can report bugs on GitHub Issues.

What’s next

Section titled “What’s next”