How to update rConfig V8 Core

After reading this page, you can update an existing rConfig V8 Core installation to the latest release. You will back up the database, configuration, and storage directory, pull the newest code from GitHub, run database migrations, clear caches, restart services, and verify the upgrade on RHEL-based systems or Ubuntu.

When to use this

Use this guide when you already have rConfig V8 Core running and want to move it to a newer release for new features, security fixes, or bug fixes. If you are deploying a fresh environment instead, complete the V8 Core installation steps first, then return here for future updates.

rConfig V8 Core follows a continuous release cycle, and updates are distributed through the GitHub repository. Review the GitHub Releases page for the version you are moving to before you start, in case it includes breaking changes or special instructions.

Prerequisites

• A running rConfig V8 Core installation with shell access to the server
• The database user and password from your .env file (needed for the backup)
• A backup directory the web user can write to (this guide uses /home/backups)
• git, composer, mysqldump, and tar available on the host
• Knowledge of your platform: RHEL-based (CentOS, Rocky, RHEL, Alma) or Ubuntu

Never update without verified backups

System failures, data corruption, or compatibility issues during an update can cause extended downtime and data loss. Before you run any update command, complete the Back up your data section below and confirm the backups restore successfully. Back up the database, the .env file, and the storage directory every time.

Back up your data

Complete all four backup steps before touching the update commands.

Step 1: Back up the database

# Navigate to a backup directory
cd /home/backups

# Create database backup with timestamp
mysqldump -u rconfig_user -p --no-tablespaces rconfig > rconfig_backup_$(date +%Y%m%d_%H%M%S).sql

# Verify the backup file was created
ls -lh rconfig_backup_*.sql

You are prompted for the database password. Use the same password configured in your .env file.

Step 2: Back up the configuration files

# Backup .env file
cp /var/www/html/rconfig/.env /home/backups/.env.backup_$(date +%Y%m%d_%H%M%S)

# Backup Apache virtual host configuration
# For CentOS/Rocky/RHEL:
cp /etc/httpd/conf.d/rconfig-vhost.conf /home/backups/rconfig-vhost.conf.backup_$(date +%Y%m%d_%H%M%S)

# For Ubuntu:
cp /etc/apache2/sites-enabled/rconfig-vhost.conf /home/backups/rconfig-vhost.conf.backup_$(date +%Y%m%d_%H%M%S)

Step 3: Back up the storage directory

# Create compressed backup of storage directory
tar -czf /home/backups/rconfig_storage_backup_$(date +%Y%m%d_%H%M%S).tar.gz /var/www/html/rconfig/storage

# Verify the backup file was created
ls -lh /home/backups/rconfig_storage_backup_*.tar.gz

Step 4: Verify the backups

# List all backup files
ls -lh /home/backups/

# Check database backup file size (should not be 0 bytes)
ls -lh /home/backups/rconfig_backup_*.sql

Automated backup script

Save the commands above as a single script at /usr/local/bin/rconfig-backup.sh and run it before every update:

#!/bin/bash
BACKUP_DIR="/home/backups"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)

echo "Starting rConfig backup at $TIMESTAMP..."

# Database backup
mysqldump -u rconfig_user -p --no-tablespaces rconfig > $BACKUP_DIR/rconfig_backup_$TIMESTAMP.sql

# .env backup
cp /var/www/html/rconfig/.env $BACKUP_DIR/.env.backup_$TIMESTAMP

# Storage backup
tar -czf $BACKUP_DIR/rconfig_storage_backup_$TIMESTAMP.tar.gz /var/www/html/rconfig/storage

echo "Backup completed: $BACKUP_DIR"
ls -lh $BACKUP_DIR/*$TIMESTAMP*

Update rConfig V8 Core

Once your backups are complete and verified, work through these steps in order.

Step 1: Check the current version

cd /var/www/html/rconfig

# Check current installed version
php artisan --version

# Check Git status
git status

Step 2: Stash local changes (if needed)

If you have local modifications that conflict with the update, stash them:

# Stash your local changes
git stash

# You can restore them later with:
# git stash pop

Step 3: Pull the latest release

CentOS, Rocky, RHEL, Alma

cd /var/www/html/rconfig

# Pull latest changes from GitHub
git pull

# If you encounter conflicts, review them and resolve manually
# or restore from your backup and try again

Ubuntu

cd /var/www/html/rconfig

# Pull latest changes from GitHub
git pull

# If you encounter conflicts, review them and resolve manually
# or restore from your backup and try again

Handling Git conflicts

If you see merge conflicts:

1. Review the conflicting files (Git names them in the output).
2. Either manually resolve the conflicts or stash and discard local changes.
3. If unsure, restore from backup and contact support.

Step 4: Update dependencies

# Update Composer dependencies
composer install --no-dev

# This may take several minutes

Step 5: Run database migrations

# Run any new database migrations
php artisan migrate

# When prompted, confirm by typing 'yes'

About database migrations

Migrations modify your database schema to support new features. They are designed to be non-destructive, but this is why a verified backup is critical.

Step 6: Sync scheduled tasks

# Sync scheduled tasks with the system
php artisan rconfig:sync-tasks

Step 7: Clear caches

# Clear all application caches
php artisan rconfig:clear-all

Step 8: Restart the web server

CentOS, Rocky, RHEL, Alma

# Restart Apache
systemctl restart httpd

# Verify Apache is running
systemctl status httpd

Ubuntu

# Restart Apache
sudo systemctl restart apache2

# Verify Apache is running
systemctl status apache2

Step 9: Restart queue workers

# Restart Supervisor to reload queue workers
systemctl restart supervisord

# Verify Supervisor is running
systemctl status supervisord

Verify the update

After updating, confirm everything is working.

Step 1: Check the application version

cd /var/www/html/rconfig
php artisan --version

Step 2: Access the web interface

Open your browser and navigate to your rConfig URL. Verify you can log in, the dashboard loads correctly, and any new features appear as expected.

Step 3: Test core functionality

• Add or view a device to confirm device management works
• Run a manual device backup
• Open an existing configuration to confirm stored configs are accessible
• Review the logs for errors:

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

Step 4: Verify services

# Check Apache status
systemctl status httpd     # CentOS/Rocky/RHEL
systemctl status apache2   # Ubuntu

# Check Supervisor status
systemctl status supervisord

# Check queue workers
php artisan queue:work --once

Common gotchas

Watch out for these during an update

• Git pull fails with conflicts. Stash local changes (git stash), pull, then git stash pop. If you do not need the local changes, reset to remote with git fetch origin && git reset --hard origin/main (this discards local edits).
• Composer install fails. Clear the Composer cache (composer clear-cache) and retry. If it still fails, update Composer itself with composer self-update --2.
• Migration errors. Confirm the database connection with php artisan db:show, then retry php artisan migrate. Check progress with php artisan migrate:status.
• Permission errors, blank page, or 500 errors after update. Re-apply ownership and permissions for your platform, then clear caches. See the commands below.

Fix permissions after an update

If you hit permission errors, a blank page, or 500 errors, reset ownership and permissions, then clear caches:

CentOS, Rocky, RHEL, Alma

cd /var/www/html/rconfig

# Fix ownership
chown -R apache:apache /var/www/html/rconfig

# Fix permissions
chmod -R 755 /var/www/html/rconfig
chmod -R 775 storage bootstrap/cache

# Clear caches
php artisan rconfig:clear-all

Ubuntu

cd /var/www/html/rconfig

# Fix ownership
chown -R www-data:www-data /var/www/html/rconfig

# Fix permissions
chmod -R 755 /var/www/html/rconfig
chmod -R 775 storage bootstrap/cache

# Clear caches
php artisan rconfig:clear-all

Roll back an update

If an update causes problems, roll back to your previous version using the backups you took.

Step 1: Stop services

# Stop Apache
systemctl stop httpd        # CentOS/Rocky/RHEL
systemctl stop apache2      # Ubuntu

# Stop Supervisor
systemctl stop supervisord

Step 2: Restore the database

# Replace 'YYYYMMDD_HHMMSS' with your backup timestamp
mysql -u rconfig_user -p rconfig < /home/backups/rconfig_backup_YYYYMMDD_HHMMSS.sql

Step 3: Restore the configuration

# Restore .env file
cp /home/backups/.env.backup_YYYYMMDD_HHMMSS /var/www/html/rconfig/.env

# Restore storage directory
cd /var/www/html/rconfig
rm -rf storage
tar -xzf /home/backups/rconfig_storage_backup_YYYYMMDD_HHMMSS.tar.gz -C /

Step 4: Revert the code

cd /var/www/html/rconfig

# View recent commits
git log --oneline -n 10

# Revert to previous commit (replace COMMIT_HASH with the actual hash)
git reset --hard COMMIT_HASH

# Or revert to the last working version
git checkout HEAD~1

Step 5: Restart services

# Start Apache
systemctl start httpd       # CentOS/Rocky/RHEL
systemctl start apache2     # Ubuntu

# Start Supervisor
systemctl start supervisord

When should you apply each update?

Use these guidelines to plan your update cadence. Always test major versions in a non-production environment first.

Update type	Recommended action
Critical security fix	Apply the same day
High-severity security fix	Apply within one week
Medium or low security fix	Apply during the next maintenance window
Patch release (8.0.x)	Low risk, apply during regular maintenance
Minor release (8.x.0)	Apply during a scheduled maintenance window
Major release (x.0.0)	Plan carefully and test in non-production first

For production systems, run updates during low-usage periods and keep multiple backup versions so you can roll back if needed.

Where to get help

When you need help with an update, gather this information first:

1. Current rConfig version (php artisan --version)
2. Operating system and version
3. Error messages from the logs
4. Steps you have already tried
5. Output of git status and git log --oneline -n 5

Then reach out through one of these channels:

• Bug reports: GitHub Issues
• Community forums: community.rconfig.com
• Video tutorials: rConfig YouTube channel

What’s next

• Install rConfig V8 Core from scratch if you are setting up a new environment
• rConfig CLI commands reference for the php artisan commands used during updates
• Troubleshoot device connectivity if backups fail after an update