Skip to content
English
More support
Contact Us
  • There are no suggestions because the search field is empty.

Migrating Hyperglance to the new RKE2 based architecture

Everything you need to know about migrating from the legacy Docker architecture to the new RKE2 architecture.

 

Am I affected?  My deployment is an AWS Instance, Azure VM or GCP VM.

Yes.  Internal to the Hyperglance instance/VM is either Docker (legacy architecture) or RKE2 (new architecture).

How do I know which architecture I'm on?

SSH in and run: sudo docker ps

If the command works and shows an output like this then you are on the legacy architecture:

CONTAINER ID   IMAGE                               COMMAND                  CREATED        STATUS                  PORTS                                                 NAMES
6a6616fda4d0   hyperglance/wildfly-v2:latest       "/usr/local/sbin/sta…"   18 hours ago   Up 18 hours (healthy)                                                         wildfly
ce9345c5a5e8   hyperglance/postgresql-v2:latest    "/usr/local/sbin/sta…"   18 hours ago   Up 18 hours (healthy)   5432/tcp                                              postgresql
0e49798ceccb   hyperglance/httpd-v2:latest         "/usr/local/sbin/sta…"   18 hours ago   Up 18 hours (healthy)   80/tcp, 0.0.0.0:443->443/tcp, :::443->443/tcp         httpd

If you are on a new RKE2 architecture you should be able to run  hg status  and get an output like this:

NAME                 READY   STATUS    RESTARTS   AGE
hyperglance-helm-0   3/3     Running   0          17h

 

Do I need to upgrade and what are the benefits?

The upgrade is recommended but you do not need to upgrade right now.  Our legacy docker architecture is still supported for the time being and you still get all the great in-app features.

Here are some of the benefits to upgrading the architecture:

  • Gain access to Hyperglance's new hg CLI tool to simplify tasks and operations.

  • Improved security - The RKE2 architecture has additional security measures that are not possible to implement with Docker Compose.
  • Future-proof - In the future new features and updates may only be exposed to RKE2 users and at some point the upgrade may become mandatory.

 

How do I upgrade?

We offer a few options so you can choose the one that suits you best:


Which option is right for me?

In general we recommend Option 1. It is easy and works for everyone.

Guidance for Marketplace Customers:

  • Follow either Option 1 or Option 3 or Option 4.

     

  • We do not recommend Option 2 for marketplace customers as this would require a 2nd active marketplace subscription which could have significant billing implications.

  • Option 4 is a somewhat easier than Option 3 if you only need to migrate account connections.

Guidance for BYOL Direct Customers
(i.e. We sold you a License Key):

  • Follow either Option 1 or Option 2 or Option 4.

  • We discourage Option 4 for Direct BYOL Customers as it still requires SSH to migrate your license key making it practically no easier than Option 2.

 


The table below summaries the options you can also click into each option to see detailed pros (✅) and cons (❗):

  Option 1 Option 2 Option 3 Option 4
In-situ upgrade? Yes No No No
Recommended for marketplace customers? Yes No Yes Yes
Recommended for direct (BYOL) customers? Yes Yes No No *
Config migrated? All All All Accounts only
BYOL license auto-migrated? Yes Yes No Yes
SSH needed between instances? No Yes No Direct customers: Yes (needed).

Marketplace customers: No (Not needed)

* We discourage Option 4 for Direct BYOL Customers as it still requires SSH to migrate your license key making it practically no easier than Option 2.

                                                                                                                                                                           

Below this point are the guides for each option

                                                                                                                                                                           

 

Option 1:  Upgrade an existing instance in-place [Easiest]

This option perform an in-situ update of the internals of your existing Instance/VM deployment.  Migrating from the legacy Docker-based stack to the new Kubernetes-based stack (RKE2).

Guide intended for:  Direct customers (BYOL) and Marketplace customers.

✅ All configuration data migrated.
✅ No need to spin up a new Instance/VM.
✅ Preserves your license key.
❗ Hyperglance deployment will be offline until the migration completes.
❗ If anything goes wrong you will need to restore from a snapshot.

 
  1. We strongly recommend creating a backup / snapshot of your current deployment first. If you need to revert for any reason a snapshot of the whole Instance/VM is the only viable restore path.
  2. SSH in to your Hyperglance instance/VM to perform the steps below.
  3. Check that your system is modern enough to support this upgrade: 
     cat /etc/docker-compose.yml | grep wildfly-v2

    If you see a line like this then your system is modern enough: 

        image: hyperglance/wildfly-v2:latest

    If you do not see any result then you first need to perform the Update 1-2025 upgrade process. 

  4. Update the Hyperglance application:
    sudo docker-compose -f /etc/docker-compose.yml pull && sudo docker-compose -f /etc/docker-compose.yml up -d --renew-anon-volumes
  5. Update the Hyperglance CLI tool:
     
    sudo hg update-cli
     
    Note: If the above command fails because the CLI is not already installed on your Hyperglance instance, you can obtain it by running the following command:
    sudo docker run --rm -it \
    -v /usr/local/bin:/app/binmap \
    docker.io/hyperglance/updatetool:latest -c "./upgrade.sh install" 
    You can confirm the availability of the Hyperglance CLI by running:
    hg version
     
  6. Start the in place migration by running the following command.
    Note: The process is one way and not reversible.

    sudo hg migrate insitu run --backup-path ~/backup.tgz --accept


  7. When the migration successfully completes, you will be presented with:
    The migration has completed successfully. It is highly recommended that you perform a reboot.
    If you created any backups in the /tmp directory, it is recommended that you copy these to a safe location as they could be wiped on reboot.
    Create a backup of the migration log files, and perform a reboot.
    mkdir ~/migration-logs && cp /tmp/hg-* ~/migration-logs
    sudo reboot now
  8. After reboot Hyperglance should come online as normal and be reachable in your browser after a short bootup period. You can also check on the status of the application using the CLI:
    hg status
 
 
 

Option 2:  Start a new instance and migrate config via SSH
[BYOL only]

This option involves deploying a fresh Hyperglance instance that is running the new Kubernetes-based stack (RKE2) and copying across your data over SSH.

Guide intended for:  Direct customers only (BYOL)

✅ All configuration data is migrated.
✅ Your old deployment will stay intact incase you need to revert.
✅ Preserves your license key (moves across the new one).
❗ You will need to provision a new Hyperglance instance or VM.
❗ The new instance requires SSH with sudoer access to the old instance.
❗ Not suitable for marketplace customers (will incur marketplace charges)

 
  1. Deploy a new BYOL instance of Hyperglance but don't activate it with a license key yet.
  2. SSH into the legacy instance:
    1. Update the Hyperglance application:
      sudo docker-compose -f /etc/docker-compose.yml pull && sudo docker-compose -f /etc/docker-compose.yml up -d --renew-anon-volumes
  3. SSH into the new instance:
    1. Update the Hyperglance CLI to the latest version: 
      sudo hg update-cli
    2. Update the Hyperglance application to the latest version: 
      sudo hg upgrade
    3. Next, you will need to enable SSH access to allow the new instance to SSH into the legacy one.

      Copy the SSH keyfile onto the new instance  and run the command below to test connectivity to the legacy instance..  Just replace the UPPERCASE placeholders with your appropriate details:
      hg migrate from-remote test \
      --address LEGACY_INSTANCE_IP_ADDRESS \
      --key PATH_TO_SSH_KEY \
      --username SSH_USERNAME \
      --port SSH_PORT

      A successful connection example is shown below:

      ec2-user@ip-10-0-13-84:~$ hg migrate from-remote test \
      --address 192.168.1.68 \
      --key ~/.ssh/docker-ssh-key \
      --username ec2-user \
      --port 22
      [INFO] SSH Return Value: root
      [INFO] Successfully connected and elevated permissions!

      If the command fails, you will need to resolve the connectivity issue before continuing.

    4. Import the config from the legacy instance.
      Just replace the UPPERCASE placeholders with your appropriate details:
      sudo hg migrate from-remote run \
      --address LEGACY_INSTANCE_IP_ADDRESS \
      --key PATH_TO_SSH_KEY \
      --username SSH_USERNAME \
      --port SSH_PORT
      If the command completed succesfully, you should see the following:
      [INFO] The migration has completed successfully. It is highly recommended that you perform a reboot.
      [INFO] If you created any backups in the /tmp directory, it is recommended that you copy these to a safe location as they could be wiped on reboot.
    5. Migrate the license key from the legacy instance.
      Just replace the UPPERCASE placeholders with your appropriate details: 
      sudo hg migrate from-remote license \
      --address LEGACY_INSTANCE_IP_ADDRESS \
      --key PATH_TO_SSH_KEY \
      --username SSH_USERNAME \
      --port SSH_PORT

       

    6. Perform a reboot: 
      sudo reboot now

       

    7. After reboot Hyperglance should come online as normal and be reachable in your browser after a short bootup period. You can also check on the status of the application using the CLI: 
      hg status

       

  4. Once everything looks good you can stop your legacy Hyperglance deployment.

     

     

    Option 3:  Start a new instance and migrate config via Zipfile
    [Marketplace only]

    This option involves deploying a fresh Hyperglance instance that is running the new Kubernetes-based stack (RKE2) and copying across your configuration as a zip-file bundle.  This is good when you cannot have both new and old deployments running concurrently such as to avoid marketplace charges.

    Guide intended for:  Marketplace customers only.

    ✅ All configuration data is migrated.
    ✅ If anything goes wrong you will still have your existing deployment.
    ✅ No SSH or network access required between the two deployments.
    ✅ New and old deployment do not need to run concurrently
    ❗ You will need to provision a new Hyperglance instance or VM.
    ❗ Not suitable for direct customers (Does not migrate BYOL license key).

     
    1. SSH into the legacy instance:
      1. Update the Hyperglance application:
        sudo docker-compose -f /etc/docker-compose.yml pull && sudo docker-compose -f /etc/docker-compose.yml up -d --renew-anon-volumes
      2. Stop the running containers.
        sudo docker stop wildfly httpd postgresql
      3. Create the backup bundle:
        sudo tar czf ~/docker-backup.tar.gz /var/lib/data
      4. Download ~/docker-backup.tar.gz to your local PC (e.g. using SCP, WinSCP, FileZilla, etc)
    2. Stop your legacy instance/VM.  You do not have to delete it.  Just make sure it's not in a running state and this will free up your marketplace subscription.
    3. Redeploy Hyperglance from the marketplace portal.  It is important to make sure you launch the same product variant that you had subscribed to.  Do not enter into any new subscription contracts as this could have significant billing implications. You should just redeploy your existing product's launch template.  If in doubt, contact us first.
    4. Copy ~/docker-backup.tar.gz from your PC to the new Hyperglance deployment (e.g. using SCP, WinSCP, FileZilla, etc)
    5. SSH into the new instance:
      1. Update the Hyperglance CLI to the latest version: 
        sudo hg update-cli
      2. Update the Hyperglance application to the latest version: 
        sudo hg upgrade
      3. Import the backup bundle:
        sudo hg migrate bundle import --bundlePath path/to/imported/bundle.tar.gz
        If the command completed succesfully, you should see the following:
        [INFO] The migration has completed successfully. It is highly recommended that you perform a reboot.
        [INFO] If you created any backups in the /tmp directory, it is recommended that you copy these to a safe location as they could be wiped on reboot.
      4. Perform a reboot: 
        sudo reboot now
      5. After reboot Hyperglance should come online as normal and be reachable in your browser after a short bootup period. You can also check on the status of the application using the CLI: 
        hg status

     

    Option 4:  Start a new instance and migrate only the account connections

    This option involves deploying a fresh Hyperglance instance that is running the new Kubernetes-based stack (RKE2) and import just the account connections via the UI.

    Guide intended for:  Direct customers (BYOL) and Marketplace customers.

    ✅ Simpler than option 3.
    ✅ If anything goes wrong you will still have your existing deployment.
    ❗ You will lose all other state (custom rules, custom dashboards, budgets, etc).
    ❗ Direct customers (BYOL) still require SSH access for license migration and should consider Option 2 instead.

    A note on license migration:
    If you are a direct customer and were sold a license key then the new instance will need SSH access to the old one in order to migrate the license key.
    If you are a marketplace customer (using marketplace deployments) then license key migration is not necessary.

    CAUTION:  To generate the account export Hyperglance has to decrypt all stored secrets and embed them as plain-text in the download.  Be careful with the file.

    1. Log in to the web UI of the legacy instance as an admin user.  Go to Settings -> Platforms.  Click Bulk Export to down the connection details.  Read the CAUTION note above!
    2. Deploy a new instance/VM of Hyperglance in a way appropriate for you:
      1. Direct customers:
        Do this by launching a new BYOL instance of Hyperglance but don't activate it with a license key yet.
      2. Marketplace customers:
        1. Stop your legacy instance/VM.  You do not have to delete it.  Just make sure it's not in a running state and this will free up your marketplace subscription.
        2. Next, redeploy Hyperglance from the marketplace portal.  It is important to make sure you launch the same product variant that you had subscribed to.  Do not enter into any new subscription contracts as this could have significant billing implications. You should just redeploy your existing product's launch template.   If in doubt, contact us first.
    3. SSH into the new instance:
      1. Update the Hyperglance CLI to the latest version: 
        sudo hg update-cli
      2. Update the Hyperglance application to the latest version: 
        sudo hg upgrade
      3. This step is for direct (BYOL) customers only.  If you are marketplace customer skip to the next step.
        1. Setup SSH access so the new instance can SSH into the old one.  See Option 2 step 3.c for more details on how to verify the SSH connection.
        2. Migrate the license key from the legacy instance.
          Just replace the UPPERCASE placeholders with your appropriate details: 
          sudo hg migrate from-remote license \
          --address LEGACY_INSTANCE_IP_ADDRESS \
          --key PATH_TO_SSH_KEY \
          --username SSH_USERNAME \
          --port SSH_PORT

           

      4. Perform a reboot: 
        sudo reboot now
      5. After reboot Hyperglance should come online as normal and be reachable in your browser after a short bootup period. You can also check on the status of the application using the CLI: 
        hg status
    4. Once everything looks good you can stop your legacy Hyperglance deployment if it's still running.