> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://docs.nvidia.com/heavyai/llms.txt. For full content including API reference and SDK examples, see https://docs.nvidia.com/heavyai/llms-full.txt. ## 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](http://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](https://docs.docker.com/engine/install/ubuntu/) — install and configure Docker Engine on Ubuntu * [NVIDIA drivers](https://docs.nvidia.com/datacenter/tesla/driver-installation-guide/) — datacenter and GPU driver installation guide * [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html) — 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` ```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](https://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](https://console.cloud.google.com/) 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: | 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/`. 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/](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** | Symptom | Likely cause | | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `gh repo clone` fails | Your GitHub account doesn't have access to `heavyai/heavydb`, or `gh auth login` hasn't been run. (This is relevant for pre-OS release cases only). | | Tar file not found or unreadable | Verify the path passed to `--tar` is absolute or relative to the `heavydb` directory, and that the file is not still transferring or compressed in an unexpected format. | | Distro mismatch error | The tar filename did not match a known distro pattern. Add `--distro=ubuntu22.04` (or `rockylinux8`) to set it explicitly. | | Blank or gray map after deployment | `MAPBOX_TOKEN` was missing or invalid when the image was built, token URL restrictions block the production host, or a Mapbox billing or scope issue. | | Zoom-to search does nothing | `GOOGLE_API_KEY` was missing when the image was built, the Geocoding API is not enabled on the project, or billing is disabled. |