Migration from Legacy Enterprise Edition

Introduction

The intended audience of this guide are users with an existing installation of HeavyAI and have access to a release package (tarball) through their legacy HEAVY.AI Enterprise Edition agreement. This guide covers the package to Docker image workflow. The package tar contains pre-compiled binaries — no compiler toolchain or deps container is required here. If you do not have access to an installation archive package, or are otherwise interested in building NVIDIA HeavyAI from source, see the full build guide instead.

Prerequisites

Confirm the following are in place before starting:

• A HeavyAI package tar file (e.g. heavyai-10.0.0dev-20260903-e14f790bdb-ubuntu22.04-x86_64-render.tar.gz)
• gh CLI installed and authenticated — run gh auth login if you haven’t already
• A GitHub token with read:packages + repo scopes — your gh auth token output typically satisfies this

1. Prepare the environment

The host that will build and run the HeavyAI Docker image must have Docker Engine, NVIDIA drivers, and nvidia-container-toolkit installed. This can be your production machine or a separate build host — the resulting image is a self-contained artifact that can be transferred afterward.

Pre-open source release: use heavyai/heavydb-internal instead of heavyai/heavydb wherever the repository name appears in this guide.

Install the following on your Linux host using the official documentation for each:

• Docker Engine — install and configure Docker Engine on Ubuntu
• NVIDIA drivers — datacenter and GPU driver installation guide
• NVIDIA Container Toolkit — enables GPU access inside Docker containers

Additionally, if this is the first time you’re installing NVIDIA HeavyAI on the machine, please install the following Docker configuration, by writing the following into /etc/docker/daemon.json

{
    "default-runtime": "nvidia",
    "exec-opts": ["native.cgroupdriver=cgroupfs"], 
    "runtimes": {
        "nvidia": {
            "args": [],
            "path": "nvidia-container-runtime"
        }
    }
}

After installing this configuration, restart Docker with this command:
sudo systemctl restart docker

Verification
Once all three are installed, confirm the GPU passthrough is working: docker run --rm nvidia/cuda:12.0-base nvidia-smi. If it prints your GPU details, the environment is ready.

2. Clone the repository

The dev-tools/dev.sh script lives in heavyai/heavydb. Clone it to your host and enter the project directory:

gh repo clone heavyai/heavydb
cd heavydb

Note: Prior to OS release, this repository requires a GitHub account with access to the HeavyAI organization (and uses repo heavyai/heavydb-internal). Ensure gh auth login has been run and your token has read:packages + repo scopes.

3. Obtain API keys & Base Image

Immerse requires two API keys for map chart functionality. These are passed as environment variables when building the Docker image — they are baked into the Immerse artifact and never written to a config file on disk.

• Mapbox — basemap tiles for pointmap, choropleth, linemap, and other geo charts
• Google Maps Geocoding — powers the zoom-to address search box on map charts

3a. Create a Mapbox access token

1. Sign in at account.mapbox.com.
2. Open Tokens → Create a token and give it a descriptive name.
3. Use a public token (begins with pk.). Do not use a secret sk. token — Immerse runs in the browser.
4. Enable at minimum these scopes: STYLES:READ, STYLES:TILES, FONTS:READ, DATASETS:READ. DATASETS:READ is only required if you use custom Mapbox Studio styles.
5. Optionally add URL restrictions to limit where the token can be used:

http://YOUR_HEAVYAI_HOST:6273/*https://YOUR_HEAVYAI_HOST/*

6. Copy the token — you will need it in Step 4.

Warning: Mapbox charges per map load and tile request beyond the free tier. URL restrictions and your own token are strongly recommended over any shared or default.

3b. Create a Google Maps Geocoding API key

1. Open Google Cloud Console and create or select a project.
2. Go to APIs & Services → Library, search for Geocoding API, and enable it.
3. Go to APIs & Services → Credentials → Create credentials → API key.
4. Copy the key.
5. Apply key restrictions if desired or required by your IT policy. Because this key is used directly within the end user’s browser, any IP-based restrictions must account for the full range of your users’ client IP addresses rather than server IPs.
   • Under Application restrictions, HTTP referrer restrictions are generally preferable to IP restrictions for browser-side keys:

http://YOUR_HEAVYAI_HOST:6273/*https://YOUR_HEAVYAI_HOST/*

• Under API restrictions, limit to Geocoding API only.

6. Ensure billing is enabled on the project. Google requires this even when usage stays within the free credit tier.

3c. Pull product base image

In order to proceed with step four (4), we will need to pull the base image upon which the product is built,a runtime container for our relevant cuda version.

docker image pull nvcr.io/nvidia/cuda:12.9.2-runtime-ubuntu22.04

4. Build the Docker image

With both API keys ready, run the image build from inside the heavydb directory. Pass the path to your package tar and the API keys as environment variables — this keeps credentials out of any config file on disk.

MAPBOX_TOKEN=pk.xxx \
GOOGLE_API_KEY=your-google-key \
  dev-tools/dev.sh build image --tar=/path/to/heavyai-10.0.0-date-hash-ubuntu22.04-x86_64-render.tar.gz

Replace pk.xxx with your Mapbox public token, your-google-key with your Google Geocoding API key from Step 3, and the --tar path with the actual location of your package file.

The build process unpacks the tar and assembles a single Docker image containing all HeavyAI components:

Build output is written to build/ubuntu22.04/logs/. If a step fails, the last 50 lines of the relevant log are printed automatically. You can also tail the Docker build log directly:

# Watch the Docker image build log in real time
tail -f build/ubuntu22.04/logs/docker-build.log

Note: The build image target infers the distro from the tar filename. If the filename does not match a known pattern, use --distro=ubuntu22.04 (or rockylinux8) to set it explicitly.

5. Confirm the image

Once the build completes, confirm that the HeavyAI product image was created:

docker image ls

You should see the new product image. For example:

REPOSITORY                              TAG       IMAGE ID       CREATED        SIZE
heavyai-ubuntu22.04-cuda-render-x86_64  10.0.0    3f9a1c2d8e4b   2 minutes ago  18.3GB

Note the full image name and tag from your output — you will need it when updating your docker-compose.yml.

The Docker image is now ready on this machine. You can use the loaded image with a docker run command or with docker compose to deploy the NVIDIA HeavyAI platform.

Next steps

With the Docker image built and confirmed, you can use docker run or an existing docker-compose.yml file to deploy, verify, and configure your HeavyAI installation. These steps vary based on your existing installation and your organization’s preferences. We suggest a quick smoke test to validate that the platform deployed successfully:

• Open up your configured immerse url, eg https://host:6273/, you should see the existing login page or redirection to SAML identity provider authentication as configured.
• Create a new dashboard, and add a point or choropleth chart. When previewing the chart creation, basemap tiles should load correctly. Once you specify an appropriate data source and measure, points or polygons (if choropleth) should render over the basemap.
• In your newly created map chart, search for a location such as “Cincinnati, OH” in the search box. The map should center over your location. This confirms the google API key is configured and deployed correctly.

Troubleshooting