On-Site Installation and Management

While the HyperX Dashboard can most easily be accessed online, it can also be installed and managed locally so that all of your project data remains on your premises.

The Dashboard is an application designed to run using several Docker containers. This allows the Dashboard to run in any environment that supports Docker containers.

There are 5 containers that compose the Dashboard:

The proxy (named hyperxdashboard_proxy).
The web server (named hyperxdashboard_frontend).
The API server (named hyperxdashboard_backend).
The database (named hyperxdashboard_mariadb).
The authentication server (named hyperxdashboard_keycloak).

Note

By installing the Dashboard locally, you have full control over all of these containers. The Dashboard does not need to connect to any external servers to work and can even be installed and run in an offline environment.

To simplify the installation and management of the Dashboard, a control tool called hx-dashboard-ctl is provided. This tool can be used to install the Dashboard and perform management actions, like updating the Dashboard or backing up its database.

Install

To install and set up the Dashboard, you must install the Dashboard Control Tool (hx-dashboard-ctl), use it to install the Dashboard, and configure HyperX to upload to your Dashboard install.

Prerequisites

A Linux machine (virtual or physical) which is based on the Debian distribution. This includes Ubuntu, Linux Mint, and many other distributions.

Important

This machine must use a 64-bit architecture.
Ensure you have the ability to run Linux commands using the “sudo” keyword to run as the root user. The hx-dashboard-ctl tool requires the use of sudo to communicate with Docker, which runs with root privileges.
Install Docker Engine on your Linux machine, following the documentation for your particular distribution. That documentation can be found here: https://docs.docker.com/engine/install/
Optional: Prepare a custom TLS certificate (a set of .crt and .key files) to use for HTTPS. See Using a Custom TLS Certificate for more information on how the Dashboard handles data encryption.

Process

Installing the Dashboard Control Tool

Download the hx-dashboard-ctl Debian package (called hx-dashboard-ctl_{VersionNumber}_amd64.deb) from the Collier Aerospace downloads website: https://downloads.collieraerospace.com/all-downloads.

Important

This download is not available to everyone. We must explicitly allow your Collier Aerospace account to access this file. If you do not see a download for it on our downloads website, contact Collier Aerospace (<info@collieraerospace.com>) to be granted access.
Open a terminal in the location of the Debian package file. You can do this through the interface of the operating system, or entirely through the terminal if on a headless distribution.
Run the command “sudo apt install ./hx-dashboard-ctl_{VersionNumber}_amd64.deb”. This will install the Dashboard control tool as one of your packages. The output should look something like this:

Install the Dashboard with the Control Tool

Now that hx-dashboard-ctl has been installed, run “sudo hx-dashboard-ctl” to launch the control tool. You will see a list of commands which can be run to manage your Dashboard server.

Optional - If you have a custom TLS certificate available, run the “set-cert” command. You will be prompted to enter the paths of your certificate’s .crt and .key files. This will copy your certificate files to the “/etc/hx-dashboard-ctl/certs” folder. When the Dashboard is installed, it will use these files for encryption.

To install the Dashboard - Type the “install” command and press enter. As part of this process, you will be prompted to enter various configuration options, described below.

Tip

For more information on the other commands, see Management Commands.

Installation Configuration

Accessible Machine IP Address - An IP address which can be used to access this machine from other computers. This should not be a loopback address like 127.0.0.1, since other computers will not be able to contact this machine at that address.
Dashboard Hostname - The address users will type into their web browsers to access the Dashboard. This must be the IP address of the machine or the DNS name of this machine if one exists. The default value for this field is the ”Accessible Machine IP Address” you entered earlier.
Dashboard Database Password - The password used by the Dashboard database. You will need to enter this password when updating or backing up the Dashboard’s database.
Keycloak Admin Password - The password of the person managing Dashboard user accounts. The username for this account is always “admin”. You can log into Keycloak as this user at the URL “https://YOUR_DASHBOARD_HOSTNAME/auth.
Dashboard Database Port - The network port used by the Dashboard container. The default value is 3306, but it can be set to any available port you choose. You should set a custom value here if you are already running a database using port 3306 on this machine.

Note

The passwords you enter will be stored using Docker Secrets. This will prevent them from being stored in plain text on your machine. The other configuration values will be stored in your Docker Swarm Stack configuration file, located at “/etc/hx-dashboard-ctl/hyperxdashboard-stack.yaml”. See Docker Stack Configuration for more details.

Once all configuration values are entered, the Dashboard will be installed and will start up.

Now that the Dashboard is installed and running, you can use your hostname to access it using a web browser. However, you still need to configure your HyperX install to upload to your Dashboard.

Configure HyperX for Uploading

To configure HyperX for uploading to your on-premises Dashboard, open the Cloud Uploader form via the “Upload to Dashboard” button in the Result tab of the Ribbon.

You must then enter your Dashboard’s hostname into the server address and the authentication server address text boxes on the “Enter Dashboard Credentials” form. Then enter your credentials from an account you created in your Dashboard.

Now that you can upload to your local Dashboard server, you will need to create a Company in the Dashboard UI to associate with your upload.

Customize Configuration

During and after install, you can configure the Dashboard to customize how it runs and how users on your network access it. For instance, you may want to change which ports are used by Dashboard services.

By default, the Dashboard uses ports 80, 443, and 3306. The database port (default 3306) can be customized when installing the Dashboard.

Note

Aside from changing the database port, there are several other configuration options that you can set during install. You can review these in Installation Configuration.

After installation is complete, you can further customize your Dashboard install by editing its “stack” configuration file.

For instance, the http and https ports (80 and 443) provide users with the best experience when connecting to the Dashboard using their browser. However, if these ports need to be changed, they can be customized by changing the Docker Stack Configuration.

Docker Stack Configuration

The hx-dashboard-ctl tool calls the Docker API to manage the Dashboard Docker containers. These containers run as part of a Docker Swarm Stack. A Stack is a group of Services which run on the Swarm. Services manage the Docker containers which run the Dashboard.

The configuration file for the Stack is generated by the hx-dashboard-ctl tool when installing the Dashboard for the first time. This file is called "hyperxdashboard-stack.yaml", and is generated in the folder “/etc/hx-dashboard-ctl”. This file can be edited to define a custom configuration for the Docker Services.

For example, this file can be edited to prevent the proxy container from communicating over port 80. The next time the Dashboard is stopped and restarted, it will use your new configuration as defined in the "hyperxdashboard-stack.yaml" file.

Caution

Keep in mind that your configuration changes in "hyperxdashboard-stack.yaml" may break some of the functionality of the hx-dashboard-ctl tool or the Dashboard itself. If you would like to edit this file, it would be safest to communicate with Collier Aerospace support to confirm that your planned changes will work as intended. Before changing any configuration, make a backup of your database just in case anything goes wrong.

Encrypt Dashboard Data

By default, the Dashboard will generate a self-signed certificate to encrypt traffic. The traffic is encrypted but will display as insecure in your browser.

You can either manually trust this certificate on your computer before uploading to the Dashboard or you can configure the Dashboard to use a trusted certificate instead of a self-signed one (recommended).

Using a Custom TLS Certificate (Recommended)

Once you have generated a TLS certificate, you should have two files. One ending in “.crt”, and the other ending in “.key”. These are the public and private keys for your certificate. Run the hx-dashboard-ctl tool and enter the “set-cert” command to configure the Dashboard to use your custom files. This can be done before installing the Dashboard itself.

Note

Your custom certificate may be part of a "chain" of certificates. For example, it may reference your internal certificate authority. If your certificate references any other certificates in its chain, you will need to include those when the set-cert command prompts you for any other certificates in your chain.

You can also change the certificate used by the Dashboard after it is installed. To do this, use the “set-cert” command to copy your files to the “/etc/hx-dashboard-ctl/certs” folder. The next time you restart the Dashboard, your new certificate will be used. To restart the Dashboard, run the “stop” command and then the “start” command using the hx-dashboard-ctl tool.

Using the Default Self-Signed TLS Certificate

If you do not provide a custom certificate, the Dashboard will automatically generate its own self-signed certificate. Here are some additional steps you must take when using the self-signed certificate.

Uploading to the Dashboard Using HyperX

Before uploading to your Dashboard from HyperX, you will need your computer to view the Dashboard’s self-signed certificate as trusted. These steps should be done on a Windows machine with HyperX installed.

Enter the Dashboard URL into a browser of your choice (this guide uses Google Chrome). Click “Not secure” and then click “Certificate is not valid”.
Export the certificate to your Downloads folder.

Then open your Downloads folder, right click the "YOUR_DASHBOARD_HOSTNAME.crt" file and click “Install Certificate”.
Click Next and then select the option to “Place all certificates in the following store”.

Click “Browse…”, then click “Trusted Root Certification Authorities” and select OK. Then click “Next”, and “Finish”.
A warning pop up asking if you are sure that you want to trust this certificate. Click yes.

Important

Everyone who wants to upload to this Dashboard server must also install this certificate in order to upload.

Now that the certificate is trusted on your machine, you can open HyperX and configure the Cloud Uploader form to upload locally. See Configuring HyperX for Uploading for more details.

Manage Dashboard Installation

The hx-dashboard-ctl tool provides several utilities to assist you as you manage your Dashboard. This section details the commands available to you and how to accomplish common tasks with them.

Management Commands

install - Configures and installs the Dashboard Docker containers. See Install the Dashboard with the Control Tool for more info.
set-cert - Updates the TLS certificate used by the Dashboard to encrypt HTTP data. See Using a Custom TLS Certificate for more info.
uninstall - Uninstalls the Dashboard Docker containers. Removes additional resources like Docker images and secrets. See Uninstalling the Dashboard for more info.
start - Starts the Dashboard Docker containers. The Dashboard starts automatically after installation and when you restart your machine. So, the "start" command is only necessary if you manually stop the Dashboard and need to restart it manually.
stop - Stops the Dashboard Docker containers. Use this command if you ever need to manually stop the Dashboard. You will have to use the "start" command to manually restart the Dashboard when you are ready.
version - Displays the version of the hx-dashboard-ctl tool.
status - Displays the status of the Dashboard Docker services. You can use this to check the version of the Dashboard Docker containers as well. See Updating the Dashboard for more info.
logs - Displays all logs from the Dashboard Docker services.
backup - Takes backups of the Dashboard and Keycloak databases and puts them in a "/etc/hx-dashboard-ctl/backups" folder. See Creating and Restoring from Backups for more info.
update - Updates an existing Dashboard installation using new Docker image versions. See Updating the Dashboard for more info.
restore - Restores the Dashboard and Keycloak databases from an existing backup. See Creating and Restoring from Backups for more info.

Updating the Dashboard

When you run the "update" command, it will load new Docker image versions from what is stored in the Control Tool. So, to update the Dashboard, you may also have to update the Control Tool. To determine what steps to take, first check the versions of the Control Tool and the Dashboard.

Update Dashboard Control Tool

To accomplish the first task, visit the Collier Aerospace downloads website (downloads.collieraerospace.com/all-downloads) to download a new version of the hx-dashboard-ctl Debian package.

Note

If you do not see a “HyperX Dashboard” section on the downloads page, contact Collier Aerospace (or email info@collieraerospace.com) to request approval to download the Dashboard. Once your account is approved for Dashboard use, you will see a Dashboard download on the downloads page.

Once you’ve downloaded the new Debian package, run this command:

“sudo apt install ./{NAME_AND_EXTENSION_OF_PACKAGE}”.

This command will upgrade your existing hx-dashboard-ctl installation to the new package version.

After the upgrade completes, run “sudo hx-dashboard-ctl version” to ensure that the hx-dashboard-ctl tool is using the new Dashboard version. If it is, you are ready to use the updated tool to update the Dashboard.

Update Dashboard

To do this, run “sudo hx-dashboard-ctl update”. Enter your Dashboard’s database password when prompted. The control tool will then take a backup of your database and attempt to migrate your database to the new version.

Note

If something goes wrong, the operation will be cancelled and your database will restore itself using the backup it created before the migration attempt.

If the migration succeeds, the control tool will configure your Dashboard to use new versions of the Dashboard containers and they will be launched. Once the new containers finish starting up, your Dashboard update is complete!

Creating and Restoring from Backups

Create Backup

You may want to create backups occasionally to ensure the security of your Dashboard’s data. To create a backup, run the command “sudo hx-dashboard-ctl backup”.

You will be prompted to enter the password for your database. After that, the control tool will back up your database and place the backup files in a folder like this: “/etc/hx-dashboard-ctl/backups/backup_20240102030405”.

Tip

To view all your backups, navigate to the folder “/etc/hx-dashboard-ctl/backups”.

Uninstalling the Dashboard

Should you wish to uninstall the Dashboard, you must run the “uninstall” command using the hx-dashboard-ctl tool. The control tool will then uninstall the Dashboard-related Docker resources running on your machine.

Once the Dashboard is uninstalled, you can also uninstall the control tool itself. To do this, run “sudo apt remove hx-dashboard-ctl”.

Note

Your backups will not be uninstalled during this process. To remove your backups, go to the “/etc/hx-dashboard-ctl” folder on your machine and delete the contents of the “backups” folder.

Manage Local Authentication Server

The Dashboard uses an open-source authentication technology called “Keycloak” to manage user accounts.

Adding Email Functionality

Keycloak works best when it has the ability to send emails. For example, when a user requests a password reset for their account, a password reset link will be emailed to the user.

However, Keycloak can only do this if an email server is specified within the Keycloak interface. This is not provided by default when you install the Dashboard. If you have an smtp server available, you can connect to it using the Keycloak interface.

Fill out the fields in the “Template” and “Connection & Authentication” sections to your liking, then click Save. If properly configured, Keycloak will then have the ability to email users. More information on this can be found on Keycloak’s website.

Note

Install

Important

Important

Tip

Note

Customize Configuration

Note

Caution

Encrypt Dashboard Data

Note

Important

Important

Manage Dashboard Installation

Note

Note

Tip

Note

Note

Manage Local Authentication Server

Recently Viewed

Didn’t find what you’re looking for?

Didn’t find what you’re looking for?