Skip to content

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.

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.

  • V8 Core on Docker Compose and root access 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-reconcile command. 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 .env file. It holds the APP_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.

  1. 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/core
    mkdir -p /root/core-backup
    docker compose exec -T db sh -c 'mariadb-dump -uroot -p"$MYSQL_ROOT_PASSWORD" --single-transaction "$MYSQL_DATABASE"' > /root/core-backup/rconfig.sql
    docker volume ls | grep storage_data

    Use 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
  2. Stop Core. Stop the containers and keep their volumes.

    Terminal window
    docker compose stop

    Never run docker compose down -v. It deletes the volumes that hold your data.

  3. 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/pro
    cd /path/to/pro
    docker login reg.rconfig.com:8443
    sed -i 's|image: mariadb:latest|image: mariadb:10.11|' docker-compose.yml
  4. Build the Pro .env file from your Core values. Copy data/.env from the Pro template, then set these variables to the values in your Core .env.

    Variable Value
    APP_KEY The exact Core key. A different key makes stored credentials unreadable.
    APP_URL The URL users open for Pro, for example http://rconfig.example.com:8080
    APP_DEBUG false
    SEED_INITIAL_DATA false
    DB_HOST, DB_PORT db and 3306
    DB_DATABASE, DB_USERNAME, DB_PASSWORD The Core values
    MARIADB_ROOT_PASSWORD The Core MYSQL_ROOT_PASSWORD
    MAIL_MAILER, MAIL_HOST, MAIL_PORT, MAIL_USERNAME, MAIL_PASSWORD, MAIL_ENCRYPTION, MAIL_FROM_ADDRESS, MAIL_FROM_NAME The Core values
    MICROSOFT_CLIENT_ID, MICROSOFT_CLIENT_SECRET, MICROSOFT_TENANT_ID, MICROSOFT_REDIRECT_URI, MICROSOFT_CLOUD The Core values. Only needed if you use Microsoft Entra ID sign-in.
    TIMEZONE The Core value

    Do not copy REDIS_HOST, APP_DIR_PATH or the HORIZON_* variables. Pro sets its own. Replace every remaining ENVOY_ 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.

  5. Start the database and restore the Core data. The dump contains your complete Core database.

    Terminal window
    docker compose up -d db
    sleep 30
    docker compose exec -T db sh -c 'mariadb -uroot -p"$MARIADB_ROOT_PASSWORD" "$MARIADB_DATABASE"' < /root/core-backup/rconfig.sql
  6. Copy the Core storage. This brings your configuration backups into Pro.

    Terminal window
    tar xzf /root/core-backup/storage.tgz -C data/storage
  7. Start Pro.

    Terminal window
    docker compose up -d
    docker compose exec app supervisorctl status
    docker compose exec -u www-data -e HOME=/tmp app php artisan list rconfig | grep migrate-reconcile

    The services apache2, horizon, redis-server and schedule-run must show RUNNING, and the last command must print rconfig: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.

  8. 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-reconcile

    A correct report ends with needs review: 0. If needs review is 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 what exists and what is missing. 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 --complete

      If 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 review is 0, record the migrations as applied:

    Terminal window
    docker compose exec -u www-data -e HOME=/tmp app php artisan rconfig:migrate-reconcile --apply
  9. 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 --force

    The output must end without errors. Pro then completes the tables that Core created with fewer columns.

  10. 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:updatedb8

    Skip this step and Pro cannot open, search or compare any backup taken before the upgrade. The command is safe to run again.

  11. Refresh roles, tasks and caches.

    Terminal window
    docker compose exec -u www-data -e HOME=/tmp app php artisan rconfig:update-rbac-data
    docker compose exec -u www-data -e HOME=/tmp app php artisan rconfig:sync-tasks
    docker compose exec -u www-data -e HOME=/tmp app php artisan rconfig:clear-all
    docker compose exec app chown -R www-data:www-data /var/www/html/rconfig8/current/storage
    docker compose restart app

    Do not run php artisan key:generate or the role and permission seeders. They are for new installations and replace your APP_KEY and roles.

  12. 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-roles
    docker compose exec -u www-data -e HOME=/tmp app php artisan rconfig:update-tag-roles

    Users with the user role still see no devices. To keep the Core behavior, where every user sees every device, also assign the devices and tags to the user role. This SQL is safe to repeat. Role ID 2 is the user role on a standard installation, so check with SELECT 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.

  13. 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"; } }'
  14. 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 down
    cd /path/to/core && docker compose start