HEAVY.AI Installation on CentOS/RHEL

This is an end-to-end recipe for installing HEAVY.AI on a CentOS/RHEL 7 machine using CPU and GPU devices.

The order of these instructions is significant. To avoid problems, install each component in the order presented.


These instructions assume the following:

  • You are installing on a “clean” CentOS/RHEL 7 host machine with only the operating system installed.

  • Your HEAVY.AI host only runs the daemons and services required to support HEAVY.AI.

  • Your HEAVY.AI host is connected to the Internet.


Prepare your Centos/RHEL machine by updating your system and optionally enabling or configuring a firewall.

Update and Reboot

Update the entire system and reboot the system if needed.

sudo yum update
sudo reboot

Install the utilities needed to create HEAVY.AI repositories and download archives

sudo yum install yum-utils curl


Follow these instructions to install a headless JDK and configure an environment variable with a path to the library. The “headless” Java Development Kit does not provide support for keyboard, mouse, or display systems. It has fewer dependencies and is best suited for a server host. For more information, see https://openjdk.java.net.

  1. Open a terminal on the host machine.

  2. Install the headless JDK using the following command:

sudo yum install java-1.8.0-openjdk-headless

Create the HEAVY.AI User

Create a group called heavyai and a user named heavyai, who will own HEAVY.AI software and data on the file system.

You can create the group, user, and home directory using the useradd command with the --user-group and --create-home switches:

sudo useradd --user-group --create-home --groups wheel heavyai

Set a password for the user:

sudo passwd heavyai

Log in with the newly created user:

sudo su - heavyai


Install HEAVY.AI using yum or a tarball.

The installation using the yum package manager is recommended to those who want a more automated install and upgrade procedure.

Install Nvidia Drivers ᴳᴾᵁ ᴼᴾᵀᴵᴼᴺ

If your system includes NVIDIA GPUs, but the drivers are not installed, install them now.

See Install NVIDIA Drivers and Vulkan on CentOS/RHEL for details.

Installing with Yum

Create a yum repository depending on the edition (Enterprise, Free, or Open Source) and execution device (GPU or CPU) you are going to use.

sudo yum-config-manager --add-repo \

Add the GPG-key to the newly added repository.

sudo yum-config-manager --save \

Use yum to install the latest version of HEAVY.AI.

sudo yum install heavyai.x86_64

If you need to install a specific version of HEAVY.AI because you are upgrading from Omnisci, or for different reasons, you must run the following command:

sudo yum install heavyai-$(yum --showduplicates list heavyai.x86_64 | \
grep $hai_version | tr -s " " | cut -f 2 -d ' ').x86_64

Installing with a Tarball

First create the installation directory.

sudo mkdir /opt/heavyai && sudo chown $USER /opt/heavyai

Download the archive and install the latest version of the software. A different archive is downloaded depending on the edition (Enterprise, Free, or Open Source) and the device used for runtime.

curl \
https://releases.heavy.ai/ee/tar/heavyai-ee-latest-Linux-x86_64-render.tar.gz \
| sudo tar zxf - --strip-components=1 -C /opt/heavyai


Follow these steps to prepare your HEAVY.AI environment.

Set Environment Variables

For your convenience, you can update .bashrc with these environment variables

echo "# HEAVY.AI variable and paths
export HEAVYAI_PATH=/opt/heavyai
export HEAVYAI_BASE=/var/lib/heavyai
export HEAVYAI_LOG=$HEAVYAI_BASE/storage/log
export PATH=$HEAVYAI_PATH/bin:$PATH" \
>> ~/.bashrc
source ~/.bashrc

Although this step is optional, you will find references to the HEAVYAI_BASE and HEAVYAI_PATH variables. These variables contain respectively the paths where configuration, license, and data files are stored and where the software is installed. Installing them is strongly recommended.


Run the systemd installer to initialize the HEAVY.AI services and the database storage.

cd $HEAVYAI_PATH/systemd

Accept the default values provided or make changes as needed.

The script creates a data directory in $HEAVYAI_BASE/storage (typically /var/lib/heavyai) with the directories catalogs, data, export and log. The directory import is created when you insert data the first time. If you are a HeavyDB administrator, the log directory is of particular interest.


Start and use HeavyDB and Heavy Immerse. ¹

Note that Heavy Immerse is not available in the OS SEdition, so if running the OSS Edition the systemctl command using the heavy_web_server has no effect.

Enable the automatic startup of the service at reboot and start the HEAVY.AI services.

sudo systemctl enable heavydb --now
sudo systemctl enable heavy_web_server --now

Configure the Firewall ᴼᴾᵀᴵᴼᴺᴬᴸ

If a firewall is not already installed and you want to harden your system, install and start firewalld.

sudo yum install firewalld
sudo systemctl start firewalld
sudo systemctl enable firewalld
sudo systemctl status firewalld

To use Heavy Immerse or other third-party tools, you must prepare your host machine to accept incoming HTTP(S) connections. Configure your firewall for external access:

sudo firewall-cmd --zone=public --add-port=6273-6274/tcp --add-port=6278/tcp --permanent
sudo firewall-cmd --reload

Most cloud providers use a different mechanism for firewall configuration. The commands above might not run in cloud deployments.

For more information, see https://fedoraproject.org/wiki/Firewalld?rd=FirewallD.

Licensing HEAVY.AI ᵉᵉ⁻ᶠʳᵉᵉ ᵒⁿˡʸ

If you are on Enterprise or Free Edition, you need to validate your HEAVY.AI instance with your license key. You can skip this section if you are using Open Source Edition. ²

  1. Open a terminal window.

  2. Enter cd ~/ to go to your home directory.

  3. Open .bashrc in a text editor. For example, vi .bashrc.

  4. Edit the .bashrc file. Add the following export commands under “User specific aliases and functions.”

  5. Save the .bashrc file. For example, in vi enter[esc]:x!

  6. Open a new terminal window to use your changes.

  7. Copy your license key from the registration email message. If you have not received your license key, contact your Sales Representative or register for your 30-day trial here.

  8. Connect to Heavy Immerse using a web browser connected to your host machine on port 6273. For example, http://heavyai.mycompany.com:6273.

  9. When prompted, paste your license key in the text box and click Apply.

  10. Log into Heavy Immerse by entering the default username (admin) and password (HyperInteractive), and then click Connect.

The $HEAVYAI_BASE directory must be dedicated to HEAVYAI; do not set it to a directory shared by other packages.

Final Checks

To verify that everything is working, load some sample data, perform a heavysql query, and generate a Pointmap using Heavy Immerse. ¹

Load Sample Data and Run a Simple Query

HEAVY.AI ships with two sample datasets of airline flight information collected in 2008, and a census of New York City trees. To install sample data, run the following command.

sudo ./insert_sample_data --data /var/lib/heavyai/storage
#     Enter dataset number to download, or 'q' to quit:
Dataset           Rows    Table Name          File Name
1)    Flights (2008)    7M      flights_2008_7M     flights_2008_7M.tar.gz
2)    Flights (2008)    10k     flights_2008_10k    flights_2008_10k.tar.gz
3)    NYC Tree Census (2015)    683k    nyc_trees_2015_683k    nyc_trees_2015_683k.tar.gz

Connect to HeavyDB by entering the following command in a terminal on the host machine (default password is HyperInteractive):

$HEAVYAI_PATH/bin/heavysql -p HyperInteractive

Enter a SQL query such as the following:

SELECT origin_city AS "Origin", 
dest_city AS "Destination", 
AVG(airtime) AS "Average Airtime" 
FROM flights_2008_10k WHERE distance < 175 
GROUP BY origin_city, dest_city;

The results should be similar to the results below.

Origin|Destination|Average Airtime
Ft. Myers|Orlando|28.666667
Orlando|Ft. Myers|32.583333

Create a Dashboard Using Heavy Immerse ᵉᵉ⁻ᶠʳᵉᵉ ᵒⁿˡʸ ¹

After installing Enterprise or Free Edition, check if Heavy Immerse is running as intended.

  1. Connect to Heavy Immerse using a web browser connected to your host machine on port 6273. For example, http://heavyai.mycompany.com:6273.

  2. Log into Heavy Immerse by entering the default username (admin) and password (HyperInteractive), and then click Connect.

Create a new dashboard and a Scatter Plot to verify that backend rendering is working.

  1. Click New Dashboard.

  2. Click Add Chart.

  3. Click SCATTER.

  4. Click Add Data Source.

  5. Choose the flights_2008_10k table as the data source.

  6. Click X Axis +Add Measure.

  7. Choose depdelay.

  8. Click Y Axis +Add Measure.

  9. Choose arrdelay.

  10. Click Size +Add Measure.

  11. Choose airtime.

  12. Click Color +Add Measure.

  13. Choose dest_state.

The resulting chart shows, unsurprisingly, that there is a correlation between departure delay and arrival delay.

¹ In the OS Edition, Heavy Immerse is unavailable.

² The OS Edition does not require a license key.

Last updated