/rconfig

rConfig V6 Core

Primary LanguagePHPGNU General Public License v3.0GPL-3.0


rConfig Logo

rConfig v6 Core

rConfig v6 Core is a free, open source, community edition of rConfig v6. It is a fully functional version of rConfig v6, with all the core features of rConfig v6 Professional, but with some limitations. Check out our features list to learn more.

Explore the docs »

Intro · Installation · Updating · Contributing · License · Support

Tests License Made with Node PHP Version Require

Intro

rConfig v6 is an enterprise grade Network Configuration Management (NCM) software package with superior NCM features and capabilities to help you easily manage configurations on large and small heterogenous networks. rConfig v6 is our flagship professional version of rConfig aimed at high value networks and business operations. rConfig v6 runs natively on many variants of Linux. Within this repo, is the code base for rConfig v6 Core, and a set of scripts to help you get started with rConfig v6 Core.

If you are looking for rConfig V6 professional, please visit https://www.rconfig.com/.

Supported OS

  • Rocky Linux 8/9+
  • RHEL Linux 8/9+
  • CentOS Linux 8/9+
  • Ubuntu 20.04+
  • Now run rConfig v6 in a Docker container! rconfig6docker repository

rConfig v6 core is completely free, you do not need an API key from rConfig to download and use this version. Please follow the instructions below to get started.

rConfig Editions

Feature rConfig Core rConfig Professional
Configuration Backup ✅ ✅
Multi-Vendor Support ✅ ✅
Unlimited Devices ✅ ✅
Enterprise Features ❌ ✅
API Access ❌ ✅
Premium Support ❌ ✅

Check out more on our features page.

(back to top)

Installation

We have made it super easy to get started with rConfig v6. Follow the steps below to get started. Check out our youtube channel for a video walkthrough of the installation process.

https://www.youtube.com/channel/rconfigV6Core

Note

Do not follow the installation steps to update existing rConfig installations. You must skip to the Updating section below.

Prerequisites

Setup a server with one of the supported OS's listed above. We recommend using a fresh install of the OS. If you are using a server that has been in production, we recommend you backup the server before proceeding.

You will need to install the following software on your server: Git 2.25+ PHP 8.1+ Composer 2.4+ Apache 2.4+ MySQL 5.7+ or MariaDB 10.5+ nodejs 14.17+ Supervisor 4.2+

We have conveniently provided scripts to help you install the required software. Head over to https://docs.rconfig.com/getstarted/os-setup to find the correct script for your OS. If you are using a different OS, you will need to install the required software manually.

Note You will need to be logged in as root when running the scripts.

Database Setup

  1. Login to your database server as root
  2. Create a new database
mysql -u root -p
CREATE DATABASE rconfig;
  1. Create a new user if required (do not use the credentials below in production). This is likely required for Ubutnu 20.04+. If you are using a different OS, you may not need to create a new user, and you can use the root account, though this is not recommended.
CREATE USER 'user1'@'localhost' IDENTIFIED BY 'password1';
GRANT ALL PRIVILEGES ON rconfig.* TO 'user1'@'localhost';
FLUSH PRIVILEGES;
  1. Exit the database
exit

rConfig Setup Steps

  1. Login as root
  2. Clone the repo
cd /var/www/html
git clone https://github.com/rconfig/rconfig.git
  1. Change directory to the repo
cd rconfig
  1. Create the .env file
cp .env.example .env
  1. Edit the .env file and update the following variables:
APP_URL="https://SERVER.DOMAIN.LOCAL"
APP_DIR_PATH=/var/www/html/rconfig
DB_HOST=DBHOST
DB_PORT=3306
DB_DATABASE=DBNAME
DB_USERNAME=DBUSER
DB_PASSWORD=DBPASS
  1. Install the required PHP packages
export COMPOSER_ALLOW_SUPERUSER=1
composer self-update --2
yes | composer install --no-dev
  1. Install apache and supervisor
chmod +x setup_apache.sh
./setup_apache.sh
  1. Install supervisor
chmod +x setup_supervisor.sh
./setup_supervisor.sh
  1. Run the installation script. This will install the required packages, setup the database, and configure the web server. The script will take a few minutes to complete.

Warning

Do not run the next command on existing rConfig deployments in an attempt to update. You must follow the instructions in the Updating section below. The command below is for new installations only.

php artisan install

If you area asked 'Add a cron entry for task scheduling?', type yes and press enter.

The output from the above should look like this:

                                         APPLICATION INSTALL.


  Packages discovery ...................................................................... 5ms DONE

  command key:generate .................................................................... 2ms DONE
  command migrate
....................................................................... 387ms DONE
  command passport:install ............................................................ 1,839ms DONE
  command rconfig:clear-all
No config updates to processes


> Illuminate\Foundation\ComposerScripts::postAutoloadDump
Generated optimized autoload files containing 6960 classes
........................................................... 7,036ms DONE
  command rconfig:sync-tasks .............................................................. 5ms DONE
  script  cache .......................................................................... 57ms DONE

  Assets publishing ....................................................................... 7ms DONE

  Add a cron entry for task scheduling? (yes/no) [no]
❯ yes

   INFO  Entry was added [* * * * * cd /var/www/html/rconfig && php artisan schedule:run >> /dev/null 2>&1].

   INFO  Install done!
  1. Update apache config file for correct server name.
# CentOS/RHEL
sudo vi /etc/httpd/conf.d/rconfig-vhost.conf
# Ubuntu
sudo vi /etc/apache2/sites-enabled/rconfig-vhost.conf

Update the ServerName to match your server's domain name.

ServerName YourServerName.domain.local
ServerAlias YourServerName.domain.local
  1. Restart apache
# CENTOS/RHEL
sudo systemctl restart httpd
# Ubuntu
sudo systemctl restart apache2
  1. Clear the cache & reset permissions
# CENTOS/RHEL
cd /var/www/html/rconfig
chown -R apache storage bootstrap/cache
php artisan rconfig:clear-all
# Ubuntu
cd /var/www/html/rconfig
chown -R www-data storage bootstrap/cache
php artisan rconfig:clear-all
  1. Open your browser and navigate to your server's domain name. You should see the rConfig login page. The default system credentials are below. Please change or remove these as soon as a new admin user is created.

Username: admin@domain.com Password: admin

Check out our docs v6docs.rconfig.com to learn more.

Running rConfig v6 in Docker

We are excited to announce that you can now run rConfig v6 in a Docker container! This new option simplifies the installation and setup process, providing an isolated environment for running rConfig v6 without the need for extensive system configurations.

For detailed instructions on setting up rConfig v6 in Docker, visit the rconfig6docker repository.

Benefits of Docker for rConfig v6

  • Easy Setup: Quickly deploy rConfig v6 with minimal configuration.
  • Isolation: Run rConfig v6 in a clean and isolated containerized environment.
  • Portability: Easily move or replicate your rConfig v6 setup across different systems.
  • Consistency: Ensure that rConfig v6 behaves the same across different machines and environments.

Quick Start

To run rConfig v6 in Docker, follow these steps:

  1. Clone the rconfig6docker repository:

    git clone https://github.com/rconfig/rconfig6docker.git

  2. Navigate to the cloned directory:

    cd rconfig6docker

  3. Build and start the Docker container:

    docker-compose up -d

  4. Access rConfig v6 by navigating to http://localhost:8080 in your browser.

For more advanced configuration options, check out the rconfig6docker documentation.

(back to top)

Updating

Important

Your advised to backup your database, .env file and storage directory at a minimum before proceeding. You should also backup your entire server if possible.

Instruction on how to update your installation of rConfig v6 Core are below. You should run the commands below as root, and you may need to use sudo if installed on Ubuntu.

Warning

If you edit any of the files in the rConfig directory, you may need to resolve conflicts when you run the git pull command. You should be familiar with git and how to resolve conflicts. If you are not, you should not edit any of the files in the rConfig directory. If you get a warning about conflicts, you can try a git stash and git pull to resolve the conflicts. If you are not familiar with git, you should seek help from a professional.

Important

As of Feb 2024, you will need to update PHP to version 8.3 when updating rConfig Core V6. You will also need to update the composer version to 2.4. You can do this by running the following commands:

# Update PHP CentOS/RHEL/ Rocky
cd /home
yum -y install wget
wget https://www.rconfig.com/downloads/php-updates/centos-php8-update.sh -O /home/centos-php8-update.sh
chmod +x centos-php8-update.sh
./centos-php8-update.sh

# Update PHP Ubuntu
cd /home
sudo apt-get install wget
wget https://www.rconfig.com/downloads/php-updates/ubuntu-php8-update.sh -O /home/ubuntu-php8-update.sh
chmod +x ubuntu-php8-update.sh
./ubuntu-php8-update.sh

rConfig V7 professional subscribers should follow the instructions in the rConfig V7 professional documentation. As the installation and update process is different.

# Centos/Rocky/RHEL
cd /var/www/html/rconfig
git pull
php artisan migrate
php artisan rconfig:sync-tasks
composer install
systemctl restart httpd
php artisan rconfig:clear-all
# Ubuntu
cd /var/www/html/rconfig
git pull
php artisan migrate
php artisan rconfig:sync-tasks
composer install
systemctl restart apache2
php artisan rconfig:clear-all

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated. We are pretty strict on code quality and style. Please follow the best practices. You should also have a strong working knowledge of PHP, Laravel, and VueJS.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

  1. Fork the Project
  2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
  3. Commit your Changes (git commit -m 'Add some AmazingFeature')
  4. Push to the Branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request for approval to merge into the develop branch

How to run tests

  1. Create a new database for testing
  2. Copy the .env.example file to .env.testing
  3. php artisan key:generate --env=testing
  4. change the APP_ENV variable in the .env.testing file to testing
  5. Update the .env.testing file with the correct database credentials
  6. Run the tests with php artisan test

Front end development requires npm install --include=dev, and npm run dev to compile the assets with vite.

If you get a 'connect ENETUNREACH on npm' command, export the following env var
export NODE_OPTIONS="--dns-result-order=ipv4first"
You can add this to the ~./bashrc file

(back to top)

License

This code base for this repository's code is distributed under License from rConfig. See LICENSE.txt for more information. rConfig v6 Professional is excluded from this license and repository.

(back to top)

Support

Although we provide this code free and open source, rConfig v6 core is based best effort support basis. You may open issues in the issue section here at github. We will try to address issues in a timely manner, but without guarantees. For prompt support and business critical environments, you should take out a subscription for rCOnfig v6 Professional. rConfig Professional subscribers should open a ticket via our normal support channels.

Acknowledgments

Inspiration, code snippets, etc.

See composer.json and package.json for a full list of dependencies, and their licenses.