# HEAVY.AI Installation on Ubuntu
This is an end-to-end recipe for installing HEAVY.AI on a Ubuntu 22.04 machine using CPU and GPU devices.
{% hint style="warning" %}
The order of these instructions is significant. To avoid problems, install each component in the order presented.
{% endhint %}
## Assumptions
These instructions assume the following:
* You are installing on a “clean” Ubuntu 22.04 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.
## Preparation
Prepare your Ubuntu machine by updating your system, creating the HEAVY.AI user (named heavyai), installing kernel headers, installing CUDA drivers, and optionally enabling the firewall.
### Update and Reboot
1. Update the entire system:
```bash
sudo apt update
sudo apt upgrade
```
2\. Install the utilities needed to create Heavy.ai repositories and download archives:
```bash
sudo apt install curl
sudo apt install libncurses5
```
3\. Install the headless JDK and the utility `apt-transport-https`:
```bash
sudo apt install default-jre-headless apt-transport-https
```
4\. Reboot to activate the latest kernel:
```bash
sudo reboot
```
### Create the HEAVY.AI User
Create a group called `heavyai` and a user named `heavyai`, who will be the owner of the HEAVY.AI software and data on the filesystem.
1. Create the group, user, and home directory using the `useradd` command with the `--user-group` and `--create-home` switches.
```bash
sudo useradd --user-group --create-home --group sudo heavyai
```
2\. Set a password for the user:
```bash
sudo passwd heavyai
```
3\. Log in with the newly created user:
```bash
sudo su - heavyai
```
## Installation
Install the HEAVY.AI using APT and a tarball.
{% hint style="info" %}
The installation using the APT package manager is recommended to those who want a more automated install and upgrade procedure.
{% endhint %}
### Install NVIDIA Drivers ᴳᴾᵁ ᴼᴾᵀᴵᴼᴺ
If your system uses NVIDIA GPUs, but the drivers not installed, install them now.\
See [install-nvidia-drivers-and-vulkan-on-ubuntu](https://docs.heavy.ai/installation-and-configuration/installation/installing-on-ubuntu/install-nvidia-drivers-and-vulkan-on-ubuntu "mention") for details.
### Installing with APT
Download and add a GPG key to APT.
```bash
curl https://releases.heavy.ai/GPG-KEY-heavyai | sudo apt-key add -
```
Add a source apt depending on the edition (Enterprise, Free, or Open Source) and execution device (GPU or CPU) you are going to use.
{% tabs %}
{% tab title="EE/Free GPU" %}
```bash
echo "deb https://releases.heavy.ai/ee/apt/ stable cuda" \
| sudo tee /etc/apt/sources.list.d/heavyai.list
```
{% endtab %}
{% tab title="EE/Free CPU" %}
```bash
echo "deb https://releases.heavy.ai/ee/apt/ stable cpu" \
| sudo tee /etc/apt/sources.list.d/heavyai.list
```
{% endtab %}
{% tab title="OS GPU" %}
```bash
echo "deb https://releases.heavy.ai/os/apt/ stable cuda" \
| sudo tee /etc/apt/sources.list.d/heavyai.list
```
{% endtab %}
{% tab title="OS CPU" %}
```bash
echo "deb https://releases.heavy.ai/os/apt/ stable cpu" \
| sudo tee /etc/apt/sources.list.d/heavyai.list
```
{% endtab %}
{% endtabs %}
Use `apt` to install the latest version of HEAVY.AI.
```bash
sudo apt update
sudo apt install heavyai
```
{% hint style="info" %}
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:
```
hai_version="6.0.0"
sudo apt install heavyai=$(apt-cache madison heavyai | grep $hai_version | cut -f 2 -d '|' | xargs)
```
{% endhint %}
### Installing with a Tarball
First create the installation directory.
```bash
sudo mkdir /opt/heavyai && sudo chown $USER /opt/heavyai
```
Download the archive and install the software. A different archive is downloaded depending on the Edition (Enterprise, Free, or Open Source) and the device used for runtime (GPU or CPU).
{% tabs %}
{% tab title="EE/FREE GPU" %}
```bash
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
```
{% endtab %}
{% tab title="EE/FREE CPU" %}
```bash
curl \
https://releases.heavy.ai/ee/tar/heavyai-ee-latest-Linux-x86_64-cpu.tar.gz \
| sudo tar zxf - --strip-components=1 -C /opt/heavyai
```
{% endtab %}
{% tab title="OS GPU" %}
```bash
curl \
https://releases.heavy.ai/os/tar/heavyai-os-latest-Linux-x86_64.tar.gz \
| sudo tar zxf - --strip-components=1 -C /opt/heavyai
```
{% endtab %}
{% tab title="OS CPU" %}
```bash
curl \
https://releases.heavy.ai/os/tar/heavyai-os-latest-Linux-x86_64-cpu.tar.gz \
| sudo tar zxf - --strip-components=1 -C /opt/heavyai
```
{% endtab %}
{% endtabs %}
## Configuration
Follow these steps to prepare your HEAVY.AI environment.
### Set Environment Variables
For convenience, you can update .bashrc with these environment variables
```bash
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
```
{% hint style="warning" %}
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. Setting them is strongly recommended.
{% endhint %}
### Initialization
Run the `systemd` installer to create heavyai services, a minimal config file, and initialize the data storage.
```bash
cd $HEAVYAI_PATH/systemd
./install_heavy_systemd.sh
```
Accept the default values provided or make changes as needed.
The script creates a data directory in `$HEAVYAI_BASE/storage` (default `/var/lib/heavyai/storage`) with the directories `catalogs`, `data`, `export` and `log`.The `import` directory is created when you insert data the first time. If you are HEAVY.AI administrator, the `log` directory is of particular interest.
### Activation
Start and use HeavyDB and Heavy Immerse. [¹](#in-the-os-edition-heavy-immerse-service-is-unavailable.)
Heavy Immerse is not available in the OSS Edition, 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.
{% tabs %}
{% tab title="EE/FREE" %}
```bash
sudo systemctl enable heavydb --now
sudo systemctl enable heavy_web_server --now
```
{% endtab %}
{% tab title="OS" %}
```bash
sudo systemctl enable heavydb --now
```
{% endtab %}
{% endtabs %}
### Configure Firewall ᴼᴾᵀᴵᴼᴺᴬᴸ
If a firewall is not already installed and you want to harden your system, install the`ufw`.
```bash
sudo apt install ufw
sudo ufw allow ssh
```
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.
```bash
sudo ufw disable
sudo ufw allow 6273:6278/tcp
sudo ufw enable
```
{% hint style="info" %}
Most cloud providers use a different mechanism for firewall configuration. The commands above might not run in cloud deployments.
{% endhint %}
For more information, see .
### Licensing HEAVY.AI ᵉᵉ⁻ᶠʳᵉᵉ ᵒⁿˡʸ
If you are using Enterprise or Free Edition, you need to validate your HEAVY.AI instance with your license key.
{% hint style="warning" %}
**Skip this section if you are on Open Source Edition** [²](#in-the-os-edition-heavy-immerse-service-is-unavailable.-1)
{% endhint %}
1. Copy your license key of Enterprise or Free Edition from the registration email message.\
\
If you do not have a license and you want to evaluate HEAVI.AI in an unlimited
enterprise environment, contact your Sales Representative or register for your 30-day trial of Enterprise Edition [here](https://www.heavy.ai/product/downloads/enterprise).\
\
If you need a Free License you can get one [here](https://www.heavy.ai/product/downloads/free).
2. Connect to Heavy Immerse using a web browser connected to your host machine on port 6273. For example, `http://heavyai.mycompany.com:6273`.
3. When prompted, paste your license key in the text box and click **Apply**.
4. Log into Heavy Immerse by entering the default username (`admin`) and password (`HyperInteractive`), and then click **Connect**.
.
### **Final Checks**
To verify that everything is working, load some sample data, perform a `heavysql` query, and generate a Pointmap using Heavy Immerse [¹](#in-the-os-edition-heavy-immerse-service-is-unavailable.)
#### 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.
```bash
cd $HEAVYAI_PATH
sudo ./insert_sample_data --data /var/lib/heavyai/storage
```
```bash
# 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):
```bash
$HEAVYAI_PATH/bin/heavysql
password: ••••••••••••••••
```
Enter a SQL query such as the following
```sql
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.
```sql
Origin|Destination|Average Airtime
Austin|Houston|33.055556
Norfolk|Baltimore|36.071429
Ft. Myers|Orlando|28.666667
Orlando|Ft. Myers|32.583333
Houston|Austin|29.611111
Baltimore|Norfolk|31.714286
```
#### Create a Dashboard Using Heavy Immerse ᵉᵉ⁻ᶠʳᵉᵉ ᵒⁿˡʸ [¹](#in-the-os-edition-heavy-immerse-service-is-unavailable.)
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**.
{% tabs %}
{% tab title="EE/FREE GPU" %}
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.\\
{% endtab %}
{% tab title="EE/FREE CPU" %}
Create a new dashboard and a Table chart to verify that Heavy Immerse is working.
1. Click **New Dashboard**.
2. Click **Add Chart**.
3. Click **Bubble**.
4. Click **Select Data Source**.
5. Choose the *flights\_2008\_10k* table as the data source.
6. Click **Add Dimension**.
7. Choose *carrier\_name*.
8. Click **Add Measure**.
9. Choose *depdelay*.
10. Click **Add Measure**.
11. Choose *arrdelay*.
12. Click **Add Measure**.
13. Choose *#Records.*
The resulting chart shows, unsurprisingly, that also the average departure delay is correlated to the average of arrival delay, while there is quite a difference between Carriers.\\
{% endtab %}
{% endtabs %}
#### ¹ In the OS Edition, Heavy Immerse is unavailable.
#### ² The OS Edition does not require a license key.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.heavy.ai/installation-and-configuration/installation/installing-on-ubuntu/centos-yum-gpu-ee.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.