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 section covers the package to Docker image workflow. If HeavyAI is run without a container on your server, you can use the provided release package and extract to the appropriate installation directory.

If you do not have access to an installation archive package, or are otherwise interested in building HeavyAI from source, see Build from Source instead.

Prerequisites

Confirm that you have downloaded and provisioned on the server a HeavyAI package tar file (e.g. heavyai-10.0.0-20260929-39952e6c25-ubuntu22.04-x86_64-render.tar.gz)

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.

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

To configure for docker, execute the following:

sudo nvidia-ctk runtime configure --runtime=docker --set-as-default
sudo systemctl restart docker

Verification

Confirm the GPU passthrough is working:

docker run --rm  nvcr.io/nvidia/cuda:12.9.2-runtime-ubuntu22.04 nvidia-smi

If it prints your GPU details, the environment is ready.

2. Clone the repository

This repository will give you access to all the source code and additional tools for building your container. Clone it to your host and enter the project directory:

cd $WORKSPACE
git clone https://github.com/heavyai/heavydb.git
cd heavydb

3. Pull product base image

This image is the pre-built bundle to provide existing users an accelerated build experience. Pull the runtime base image for your relevant CUDA version (if you did not pull it in test above):

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

4. Build the Docker image

Run the image build from inside the heavydb directory. Pass the path to your package tarball with the --tar option:

ev-tools/dev.sh build image \
--tar=/path/to/heavyai-10.0.0-20260929-39952e6c25-ubuntu22.04-x86_64-render.tar.gz \
--product-base-image=nvcr.io/nvidia/cuda:12.9.2-runtime-ubuntu22.04

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

Component	Description
`Immerse`	Frontend map and chart UI (API keys baked in here)
`WebServer`	HeavyAI web server
`HeavyIQ`	AI query assistant
`GEOS DSOs`	Geometry shared libraries
`HeavyDB`	Core database engine
Docker image	Final packaged container image

Build output is written to build/ubuntu22.04/logs/. To tail the Docker 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.