How to upgrade rConfig V8 Core to Pro on Docker
Upgrade rConfig V8 Core to V8 Pro on Docker
Section titled “Upgrade rConfig V8 Core to V8 Pro on Docker”After reading this page, you can move an rConfig V8 Core installation that runs on Docker Compose to V8 Pro and keep your devices, credentials, configuration backups, users, SMTP and Microsoft Entra ID settings.
When to use this
Section titled “When to use this”Use this guide when your V8 Core server runs from the rconfig8coredocker Compose project (see Install rConfig V8 Core with Docker) and you want V8 Pro on the same server. The upgrade runs next to Core: Core is stopped, not deleted, so you can go back to it at any point.
This page covers Docker only. For a Core installation on Linux without Docker, see the V8 Core to V8 Pro upgrade guide.
Prerequisites
Section titled “Prerequisites”- V8 Core on Docker Compose and
rootaccess to the server. - A V8 Pro subscription and the credentials for the private registry
reg.rconfig.com:8443. See V8 Pro Docker deployment in the V8 Pro documentation. - A V8 Pro image that includes the
rconfig:migrate-reconcilecommand. Step 7 shows how to check. - Enough free disk space for a full copy of the Core database and storage.
- A maintenance window. Core is offline from step 2 until Pro is running.
- Your Core
.envfile. It holds theAPP_KEY, which encrypts your device credentials.
How do I upgrade V8 Core to V8 Pro on Docker?
Section titled “How do I upgrade V8 Core to V8 Pro on Docker?”All commands run as root. Replace /path/to/core with the directory of your Core Compose project and /path/to/pro with the directory where you clone the Pro project.
-
Back up Core. Run these commands in the Core project directory. Keep the backup until Pro has run for a few days.
Terminal window cd /path/to/coremkdir -p /root/core-backupdocker compose exec -T db sh -c 'mariadb-dump -uroot -p"$MYSQL_ROOT_PASSWORD" --single-transaction "$MYSQL_DATABASE"' > /root/core-backup/rconfig.sqldocker volume ls | grep storage_dataUse the volume name from the last command in the next one, then copy the configuration files:
Terminal window docker run --rm -v <storage_data_volume>:/s -v /root/core-backup:/b alpine tar czf /b/storage.tgz -C /s .cp .env docker-compose.yml /root/core-backup/grep ^APP_KEY= .env > /root/core-backup/APP_KEY.backup -
Stop Core. Stop the containers and keep their volumes.
Terminal window docker compose stopNever run
docker compose down -v. It deletes the volumes that hold your data. -
Get the Pro Docker files. Clone the Pro project, log in to the registry and pin the database to the same MariaDB version as Core.
Terminal window git clone https://github.com/rconfig/rconfig8docker.git /path/to/procd /path/to/prodocker login reg.rconfig.com:8443sed -i 's|image: mariadb:latest|image: mariadb:10.11|' docker-compose.yml -
Build the Pro
.envfile from your Core values. Copydata/.envfrom the Pro template, then set these variables to the values in your Core.env.Variable Value APP_KEYThe exact Core key. A different key makes stored credentials unreadable. APP_URLThe URL users open for Pro, for example http://rconfig.example.com:8080APP_DEBUGfalseSEED_INITIAL_DATAfalseDB_HOST,DB_PORTdband3306DB_DATABASE,DB_USERNAME,DB_PASSWORDThe Core values MARIADB_ROOT_PASSWORDThe Core MYSQL_ROOT_PASSWORDMAIL_MAILER,MAIL_HOST,MAIL_PORT,MAIL_USERNAME,MAIL_PASSWORD,MAIL_ENCRYPTION,MAIL_FROM_ADDRESS,MAIL_FROM_NAMEThe Core values MICROSOFT_CLIENT_ID,MICROSOFT_CLIENT_SECRET,MICROSOFT_TENANT_ID,MICROSOFT_REDIRECT_URI,MICROSOFT_CLOUDThe Core values. Only needed if you use Microsoft Entra ID sign-in. TIMEZONEThe Core value Do not copy
REDIS_HOST,APP_DIR_PATHor theHORIZON_*variables. Pro sets its own. Replace every remainingENVOY_placeholder with the value from your subscription.If the Pro URL differs from the Core URL, update the redirect URI of your Entra ID app registration to
<APP_URL>/auth/callback/microsoft. See Microsoft SSO setup in the V8 Pro documentation. -
Start the database and restore the Core data. The dump contains your complete Core database.
Terminal window docker compose up -d dbsleep 30docker compose exec -T db sh -c 'mariadb -uroot -p"$MARIADB_ROOT_PASSWORD" "$MARIADB_DATABASE"' < /root/core-backup/rconfig.sql -
Copy the Core storage. This brings your configuration backups into Pro.
Terminal window tar xzf /root/core-backup/storage.tgz -C data/storage -
Start Pro.
Terminal window docker compose up -ddocker compose exec app supervisorctl statusdocker compose exec -u www-data -e HOME=/tmp app php artisan list rconfig | grep migrate-reconcileThe services
apache2,horizon,redis-serverandschedule-runmust showRUNNING, and the last command must printrconfig:migrate-reconcile. If it prints nothing, the Pro image is too old for this upgrade: pull a newer one before you continue. The login page returns an error until step 9 finishes. That is expected, because Pro cannot run on an unmigrated Core database. -
Check which migrations Core already applied. The report changes nothing.
Terminal window docker compose exec -u www-data -e HOME=/tmp app php artisan rconfig:migrate-reconcileA correct report ends with
needs review: 0. Ifneeds reviewis greater than 0, those migrations are only partly applied: Core has some of what they create and lacks the rest. Each one is listed with whatexistsand what ismissing. Do not continue to step 9 yet.-
An entry says
can be completed automatically. The missing pieces are columns, indexes or keys that rConfig can add. Preview exactly what it adds. This prints the SQL and changes nothing:Terminal window docker compose exec -u www-data -e HOME=/tmp app php artisan rconfig:migrate-reconcile --completeIf the SQL looks right, add the missing pieces and record the migrations as applied:
Terminal window docker compose exec -u www-data -e HOME=/tmp app php artisan rconfig:migrate-reconcile --apply --complete -
An entry does not say that. Stop. Restore your backup if needed and contact rConfig support with the report.
When
needs reviewis 0, record the migrations as applied:Terminal window docker compose exec -u www-data -e HOME=/tmp app php artisan rconfig:migrate-reconcile --apply -
-
Run the migrations. This creates everything Pro needs that Core does not have.
Terminal window docker compose exec -u www-data -e HOME=/tmp app php artisan migrate --forceThe output must end without errors. Pro then completes the tables that Core created with fewer columns.
-
Update the paths of your configuration backups. Core stores the full path of every backup file, and Pro uses a different directory. This command rewrites the paths of your configuration backups, EOC definitions and policy definitions.
Terminal window docker compose exec -u www-data -e HOME=/tmp app php artisan rconfig:updatedb8Skip this step and Pro cannot open, search or compare any backup taken before the upgrade. The command is safe to run again.
-
Refresh roles, tasks and caches.
Terminal window docker compose exec -u www-data -e HOME=/tmp app php artisan rconfig:update-rbac-datadocker compose exec -u www-data -e HOME=/tmp app php artisan rconfig:sync-tasksdocker compose exec -u www-data -e HOME=/tmp app php artisan rconfig:clear-alldocker compose exec app chown -R www-data:www-data /var/www/html/rconfig8/current/storagedocker compose restart appDo not run
php artisan key:generateor the role and permission seeders. They are for new installations and replace yourAPP_KEYand roles. -
Assign your devices to roles. Pro shows a user only the devices that belong to one of the user’s roles. Core has no such rule, so after the upgrade no device belongs to any role and the device list is empty for everyone. Give every device and tag to the Admin role:
Terminal window docker compose exec -u www-data -e HOME=/tmp app php artisan rconfig:update-device-rolesdocker compose exec -u www-data -e HOME=/tmp app php artisan rconfig:update-tag-rolesUsers with the
userrole still see no devices. To keep the Core behavior, where every user sees every device, also assign the devices and tags to theuserrole. This SQL is safe to repeat. Role ID2is theuserrole on a standard installation, so check withSELECT id, name FROM roles;if you are unsure.Terminal window docker compose exec -T db sh -c 'mariadb -uroot -p"$MARIADB_ROOT_PASSWORD" "$MARIADB_DATABASE" -e "INSERT INTO device_role (device_id, role_id) SELECT d.id, 2 FROM devices d WHERE NOT EXISTS (SELECT 1 FROM device_role dr WHERE dr.device_id = d.id AND dr.role_id = 2); INSERT INTO tag_role (tag_id, role_id) SELECT t.id, 2 FROM tags t WHERE NOT EXISTS (SELECT 1 FROM tag_role tr WHERE tr.tag_id = t.id AND tr.role_id = 2);"'Skip the SQL if you want to limit each team to its own devices, and assign the devices to roles yourself.
-
Check the upgrade. Open the Pro URL and sign in with a Core account. Then confirm each item:
- Settings, Info, About shows the Pro edition.
- The device list shows every device when you sign in as an administrator.
- The device, credential, template and task counts match Core.
- A device backup opens and shows its configuration text.
- Each user keeps the permissions of their Core role.
- A test email arrives, and Microsoft Entra ID sign-in works if you use it.
To verify credentials from the command line, check that they decrypt with your key:
Terminal window docker compose exec -u www-data -e HOME=/tmp app php artisan tinker --execute='foreach (DB::table("device_credentials")->get() as $r) { try { Crypt::decryptString($r->cred_password); echo "id{$r->id}: OK\n"; } catch (Throwable $e) { echo "id{$r->id}: FAILED\n"; } }' -
Go back to Core if needed. Stop Pro and start Core. Your Core data was never changed.
Terminal window cd /path/to/pro && docker compose downcd /path/to/core && docker compose start
What’s next
Section titled “What’s next”- Harden your Pro server and configure SSL before you expose it to users.
- Update V8 Pro when a new version is released.
- Set up Microsoft Entra ID sign-in if you changed the Pro URL.