Skip to main content

Preface

This page describes the setup process for the Qbilon Platform. The setup for Qbilon Suite is available here: Qbilon Suite Installer. Qbilon Platform is available as either a “Software as a Service” (SaaS) solution or an on-premises installation. For the SaaS version, you only need the access credentials provided via email and your specific Qbilon instance URL. If you want to install Qbilon on your own hardware and manage the installation yourself, this document provides everything you need for installation, setup, and configuration.

System Requirements

Qbilon is a Kubernetes-based application. For simple on-premises setups, we have provided a single-node setup to remove the hassle of setting up your own Kubernetes cluster. However, the hardware requirements vary depending on your workload, i.e., the amount of data you load into Qbilon and the number and type of tasks you plan to run in parallel on your Qbilon instance.

Test Setup

This setup is ideal for testing Qbilon initially and can handle up to 10,000-25,000 assets and two to three parallel tasks or automations.
  • 1 VM,
  • 4 assigned CPU cores,
  • 16 GB RAM and
  • a SSD with 50 GB capacity.
A smaller hardware setup will fail to install Qbilon at the Keycloak installation step.

Standard Setup

This setup is well-suited for most use cases and can handle up to 100,000 assets and five to ten parallel tasks or automations.
  • 1 VM,
  • 8 CPU cores,
  • 32 GB RAM and
  • a SSD with 100 GB capacity.

High Load Setup

Depending on the number of additional parallel tasks or automations you want Qbilon to run, this setup should be adapted accordingly:
  • 1 VM,
  • 8 CPU cores, plus 0.5 CPU cores per additional parallel task or automation,
  • 32 GB RAM, plus 1 GB per additional parallel task or automation and
  • a SSD with 250 GB capacity.
Please note that these are estimates. Depending on the tasks, you may need more CPU/RAM if they process lots of data simultaneously, or more CPUs if they are computationally intensive.

Enterprise Setup

If you need high availability and elastic scaling via dedicated node pools for your on-premises setup, don’t hesitate to contact us. We will be happy to provide assistance tailored to your needs.

Prerequisites

Domain

A Qbilon on-premises installation requires a domain and cannot be used with an IP address alone. To use Qbilon in an on-premises installation, you must provide a valid (sub)domain for the machine on which you are installing Qbilon. There are three ways to do this.
  • 1 – For production purposes:
    • To make Qbilon reachable from the internet, add an explicit A record for the domain in your DNS provider that points to the IP address of the machine on which you plan to install Qbilon.
    • If you only want Qbilon to be reachable on your intranet, add the entry to your internal DNS server.
  • For local testing purposes (these solutions will only work on the machine on which the changes were applied):
    • 2 – Edit the hosts file on your operating system to let the domain redirect to your IP address:
      • Windows: Open the file C:\Windows\System32\drivers\etc\hosts.
      • Mac OS: Open the file /etc/hosts or /private/etc/hosts.
      • Linux: Open the file /etc/hosts.
      • … and add a new line <your IP> <your domain> , e.g., 10.8.0.1 qbilon.acme.com
    You may need to restart your machine after editing the hosts file.
    • 3 – If you don’t have permission to edit your system’s host file, you can also start Chrome with an additional command-line parameter (not via PowerShell but “cmd”) on Windows.:
The path to your Chrome installation may be different from the one displayed here. Please change it accordingly. Also, replace qbilon.acme.com with the value you chose for QB_DOMAIN during installation, and replace 10.8.0.1 with the IP address of the machine on which you are installing Qbilon.

Operating System

We highly recommend using Ubuntu 24.04. LTS server. Although any other Linux-based operating system should work in theory, Qbilon was specifically tested with Ubuntu 24.04, and we strongly encourage you to use it.

User Rights

During installation, you will need a Linux user that can run command with elevated privileges (sudo).

Firewall Rules

To install and run Qbilon without networking issues, your firewall’s “allow list” should include the following domains and their respective ports:

Installing Qbilon

Installation

The following scripts are also explained in detail below the setup instructions.
  1. Open a shell on the machine on which you want to install Qbilon and as a user with the above-mentioned user rights, execute the following command:
During installation you will be asked for the domain under which your Qbilon installation will be reachable (QB_DOMAIN) and the URL to which all unknown requests shall be redirected (QB_REDIRECT_URL).
  1. The above command can be supplemented with the following optional parameters so that the installation process runs completely without prompts:
    1. -d <domain>, e.g. “-d test.local”
    2. -r <redirect_url>, e.g. “-r https://qbilon.io” The command would then look like:
  2. Executing the script may take up to 15 minutes. At the end, you should receive the initial access credentials generated for your installation. They will look like this:
    2 – On-Prem Setup: Installation
    • Note: Please copy those so that you don’t forget them.
    • The password provided for Qbilon has to be changed during the first login.
    • Keycloak is the identity management solution used by Qbilon and is accessible at https://<QB_DOMAIN>/keycloak/.
    • Qbilon itself is the main application and is reachable under https://<QB_DOMAIN>/.
  3. Depending on your “Domain” setup, you can now access Qbilon directly or via a specially configured Chrome browser.
If you try to access your machine’s IP address directly, the setup will redirect you to the provided QB_REDIRECT_URL.
Newer browsers sometimes try to prevent you from accessing webpages with self-signed SSL certificates, which is the standard for on-prem Qbilon. If you encounter the case where the browser doesn’t provide you a button to proceed nevertheless, then just click into the browser window and type thisisunsafe and hit enter.

Explanation

  • The above command downloads and executes the following script:
  • The installation script executes the following steps:
    • update the package manager information,
    • install Python and Python Venvs for Ansible as well as Unzip to extract the setup,
    • create a directory called qbilon and move the current working location to this folder,
    • create a virtual environment for Ansible in Python called ansible,
    • activate the environment (→ your terminal should look like this 2 – On-Prem Setup: Explanation),
    • install Ansible and the official Python client library for Kubernetes in the environment,
    • download Qbilon’s Ansible playbooks for the on-prem setup,
    • unzip those playbooks into your current folder and
    • execute the Ansible playbook which will request two values from you via prompt:
      • QB_DOMAIN: The (sub-)domain under which Qbilon will be reachable, e.g., qbilon.acme.com .
      • QB_REDIRECT_URL: the redirect URL to which the installation shall redirect any unknown request to e.g., https://acme.com
  • Note: It is expected that there is the following error message during the first execution of the Ansible playbook: 2 – On-Prem Setup: ExplanationThis just means Ansible didn’t find the needed software and therefore will install it.
  • Note: By far, the longest steps to execute in the Ansible playbook are the installation of Postgres and Keycloak.

License Activation

The following login screen is displayed when you create a new Qbilon instance:
2 – On-Prem Setup: License Activation
For on-premises instances, simply enter the credentials provided to you during installation. Then, you will be prompted to enter the license key you received from Qbilon.
2 – On-Prem Setup: License Activation
After entering your Licence Key and clicking on “Activate”, Qbilon will calculate your unique System ID and display it on the next screen.
2 – On-Prem Setup: License Activation
Follow the Get your Activation Code link to be redirected to the activation page. There, you can enter your License Key and System ID to generate an Activation Code.
2 – On-Prem Setup: License Activation
Finally, navigate back to your Qbilon instance and enter the generated Activation Code. Congratulations! You have successfully unlocked Qbilon and can now begin automatically capturing, analyzing, and optimizing your IT landscape.

Administrating Qbilon

Upgrading

Upgrading from Qbilon v3.0 onwards can be done by simply re-running the initial installation command. To do so, reconnect to the machine on which you installed Qbilon, and, if not already the case, go into the Qbilon folder (by default, this would be ~/qbilon). Afterwards execute the following script:
Please note that starting with Qbilon v3.13, upgrades are only possible from one “minor version” to the next:

Changing Domain After Setup

If you want to change the domain under which your qbilon instance is reachable after the initial installation you will have to perform one change in Keycloak for Qbilon to work again afterwards. For this you have to:
  1. Open Keycloak, usually reachable under https://<QB_DOMAIN>/keycloak
  2. Log in with the Keycloak superadmin credentials that have been presented to you during the installation.
  3. In the dropdown in the upper left select the qbilon realm
  4. In the clients select qbilon-app
2 – On-Prem Setup: Changing Domain After Setup
  1. Replace all occurrences of your old URL with the new one.
The trailing /* must be preserved for Valid redirect URIs
2 – On-Prem Setup: Changing Domain After Setup

Get Access Credentials After Setup

If you have not written down the original access credential for Qbilon or Keycloak or lost them somehow, then there is still a possibility to retrieve them afterwards. For this you have to open a terminal on the machine where you installed Qbilon and can then enter one of the following commands: For Keycloak credentials:
For Qbilon credentials:
If you have already changed the initial credentials for Qbilon during your first login, then these will not be accessible.

Inspecting Qbilon Installation

If you want to deeply inspect your qbilon installation we recommend to install K9s on the machine where you installed Qbilon. This can easily be done via these commands: x86:
ARM:
If you then start K9s via k9s and press 0 you should see a healthy qbilon installation looking similar to this:
2 – On-Prem Setup: Inspecting Qbilon Installation

Troubleshooting

TASK [Install keycloak] failed Occasionally, the Ansible playbook will fail with the following error message: 2 – On-Prem Setup: Troubleshooting In those cases, the root cause may be that it took Keycloak’s database too long to start up. To fix this, clear the installation so far by executing the following command:
After that, simply reinstall the software by entering the following command:
Command ‘ansible-playbook’ Not Found Before you can use the Ansible command, you must enable the Python virtual environment using the following command:
You can then use the Ansible command in the same way as during installation. If you want to exit the environment, use the command deactivate. None of the Above Worked If you have tried all of the above instructions and are still experiencing issues, please don’t hesitate to contact us via a support ticket. We will respond as quickly as possible.

Uninstalling Qbilon

We are very sorry to see you go! If there was anything that didn’t suit your needs or didn’t work, please let us know. All feedback is highly welcome. Leaving is usually hard, but uninstalling Qbilon is luckily not. We have made it easy to uninstall Qbilon from your systems again via an additional Ansible playbook. This simple script is located in the qbilon folder and lets you uninstall Qbilon: