rConfig V8 Core Installation Guide for Linux

After reading this page, you can install rConfig V8 Core on a supported Linux server from a fresh OS, configure the database, web server, and queue worker, and log in to the web interface for the first time. This covers the free, open-source edition end to end.

When to use this

Follow this guide for a manual installation of rConfig V8 Core directly onto a Linux host. Use it for a first-time deployment on a fresh server. If you prefer containers, follow the Docker setup guide instead, and if you are moving from an older release, see the update process.

Prerequisites

• A fresh installation of one of the supported operating systems:
  • Rocky Linux 8/9+ (recommended)
  • CentOS 8/9+
  • RHEL 8/9+
  • Ubuntu 22.04+
  • AlmaLinux 8/9+
  • AWS Linux 2023
• Root or sudo access to the server
• Basic command-line familiarity
• The dependencies installed by the automated setup script in the OS Configuration Guide
• Around 30 to 45 minutes to complete the installation

Automated setup scripts

The OS Configuration Guide provides scripts that install PHP, the web server, the database, and supporting packages in one pass. Run the script for your distribution before starting Step 1.

Installation overview

The installation runs in seven steps:

1. OS configuration: install required software dependencies
2. Database setup: create the database and user
3. Application installation: clone the repository and configure
4. Web server configuration: set up the Apache virtual host
5. Queue worker configuration: set up Supervisor
6. Run installation wizard: complete setup
7. Final configuration: set permissions and clear caches

Step 1: OS configuration

Install the software dependencies rConfig V8 Core requires before configuring the database and application. The fastest path is the automated setup script for your operating system, which installs PHP, the web server, the database, and supporting packages in one pass.

See the OS Configuration Guide to download and run the script for your OS (Rocky, RHEL, Alma, CentOS, or Ubuntu). Once it completes, continue with the database setup below.

Step 2: Database setup

Create a dedicated database and user for rConfig.

1. Log in to MySQL or MariaDB:

   # For systems with a MariaDB/MySQL root password set
   mysql -u root -p
   
   # For systems without a root password (Ubuntu often defaults to this)
   sudo mysql

2. Create the database, user, and grants:

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

3. Verify the new credentials connect:

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

Password security

Replace your_secure_password with a strong, unique password, and record it securely. You need it again during application configuration in Step 3.

Step 3: Application installation

Clone the rConfig repository and prepare the application.

1. Clone the repository into the web directory:

   # Navigate to the web directory
   cd /var/www/html
   
   # Clone the repository
   git clone https://github.com/rconfig/rconfig.git
   
   # Navigate into the application directory
   cd rconfig

2. Create the environment file from the example:

   # Copy the example environment file
   cp .env.example .env
   
   # Edit the environment file with your settings
   nano .env

3. Update the application and database 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

   Key variables to set:

   • APP_URL: the URL where rConfig is accessed (use your server hostname or IP)
   • APP_DIR_PATH: path to the 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

4. Install the PHP dependencies with Composer:

   # 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 step downloads all required PHP packages and may take several minutes.

Step 4: Web server configuration

Configure Apache to serve the rConfig application. The setup script is the same on all distributions. Only the virtual host file path and the restart command differ, so run the script first, then follow the tab for your OS.

1. Run the Apache setup script, which creates the virtual host configuration:

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

2. Edit the virtual host to match your server hostname, then restart Apache:

CentOS / Rocky / RHEL / Alma

# 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

Ubuntu

# 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.

1. Run the Supervisor setup script:

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

2. Verify Supervisor is running, and start it if needed:

   # Check Supervisor status
   systemctl status supervisord
   
   # If not running, start and enable it
   systemctl start supervisord
   systemctl enable supervisord

Step 6: Run installation wizard

Run the rConfig installation wizard to complete setup:

# Run the installation wizard
php artisan v8core:install

During the wizard, you are prompted to:

1. Confirm the database connection
2. Run database migrations
3. Seed initial data
4. Generate the application key
5. Configure cron scheduling: type yes when asked

Cron scheduling

When prompted about cron scheduling, type yes and press Enter. This ensures automated backup jobs and system maintenance tasks run on schedule.

The wizard displays progress and confirms successful completion.

Step 7: Final configuration

Set the correct file ownership and clear application caches.

CentOS / Rocky / RHEL / Alma

cd /var/www/html/rconfig

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

# Clear all caches
php artisan rconfig:clear-all

Ubuntu

cd /var/www/html/rconfig

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

# Clear all caches
php artisan rconfig:clear-all

Access rConfig for the first time

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

http://your-server.domain.com

or

http://your-server-ip

Log in with the default credentials:

• Email: admin@domain.com
• Password: admin

Change the default credentials immediately

The default admin@domain.com account is well-known and is a security risk if left in place. Immediately after first login:

1. Create a new admin user with your own email address.
2. Verify the new user can log in.
3. Delete or disable the default admin@domain.com account.

Post-installation steps

Create a new admin user

1. Log in with the default credentials.
2. Navigate to Settings then Users.
3. Click Add User.
4. Create a new user with the admin role and your real email address.
5. Log out and confirm the new account works.

For full account management detail, see managing users in rConfig.

Remove the default admin

After confirming your new admin account works:

1. Log in with your new account.
2. Navigate to Settings then Users.
3. Disable or delete the admin@domain.com account.

Configure SSL/TLS

For production deployments, encrypt traffic with SSL/TLS. Use Let’s Encrypt for free certificates, or your organisation’s PKI. See the SSL configuration guide for the full procedure.

Update device templates

Download the latest vendor templates from GitHub:

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

Add your first device

1. Navigate to Devices then Add Device.
2. Enter the device details (name, IP, credentials).
3. Assign the device to a category (command group).
4. Save and test connectivity.

For the full workflow, see adding and managing devices.

Verification checklist

After installation, confirm each item:

• The web interface loads at the server URL
• You can log in with your new admin credentials
• The default admin account is removed or disabled
• Apache is running: systemctl status httpd (or apache2)
• Supervisor is running: systemctl status supervisord
• The database connection succeeds
• You can add and view devices
• Device templates are updated
• The scheduler (cron) is configured

Common gotchas

Watch out for these during installation

• Run composer install with COMPOSER_ALLOW_SUPERUSER=1 exported, or Composer refuses to run as root and the dependency install fails partway through.
• On Ubuntu the virtual host lives at /etc/apache2/sites-enabled/rconfig-vhost.conf and you must run a2enmod rewrite. On RHEL-family systems it lives at /etc/httpd/conf.d/rconfig-vhost.conf. Editing the wrong path leaves Apache serving a 404 or 500.
• A blank page or 500 error after install is almost always a permissions issue. Re-run the chown on storage and bootstrap/cache for your web user (apache or www-data), then clear caches.
• Skipping the cron prompt in the wizard means scheduled backups never run. If you answered no, re-run php artisan v8core:install and answer yes.

Troubleshooting

Why can’t I access the web interface?

Check the Apache service and restart it:

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

# Ubuntu
systemctl status apache2
systemctl restart apache2

Check that the firewall allows HTTP and HTTPS:

# 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

How do I fix 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

How do I resolve database connection errors?

Test the connection directly:

mysql -u rconfig_user -p rconfig

Then verify the .env settings:

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

Why aren’t queue jobs processing?

Check and restart Supervisor, then review its logs:

# Check status
systemctl status supervisord

# Restart if needed
systemctl restart supervisord

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

Why do I get a blank page or 500 error?

Clear caches:

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

Re-set ownership on the writable directories:

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

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

Then check the application log:

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

• Documentation: v8coredocs.rconfig.com
• Bug reports and feature requests: GitHub Issues
• Community forums: community.rconfig.com

For business-critical environments, rConfig V8 Pro (a separate edition) adds priority support with an SLA, advanced features, and enterprise integrations. See the Pro documentation and rconfig.com for details.

What’s next

• Get started with rConfig V8 Core: learn the basic operations
• Add and manage devices: configure your first devices
• Harden your installation: secure the deployment for production