Skip to navigation
Installation and ConfigurationInstallation

Build from Source

View as Markdown

This document outlines the steps to download, build, and deploy the open source edition of NVIDIA HeavyAI.

Prerequisites

Confirm the following is in place before starting:

  • Docker Engine, NVIDIA drivers, and nvidia-container-toolkit installed on the build host (see Step 1)

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:

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 the build container

The HeavyAI build system compiles all components inside a deps container, ensuring a consistent toolchain regardless of what is installed on the host. Pull the deps image for your target distribution before building, executing the below in your heavydb (or heavydb-internal) cloned repository folder:

# Ubuntu 22.04 (default and recommended)
dev-tools/dev.sh build deps --distro=ubuntu22.04

Other supported distributions:

# Rocky Linux 8
dev-tools/dev.sh build deps --distro=rockylinux8

Note: Pulling the deps image is a one-time operation per distro. Building the deps image from scratch (if no pre-built image is available) is a multi-hour process; pulling a pre-built image from GHCR is the expected workflow. The build system auto-detects the local deps image on subsequent runs and prefers Ubuntu over Rocky when multiple images are present. Override with --deps-image=<image> if needed.

4. Build the Docker image

Run the full build from inside the heavydb directory.  

  dev-tools/dev.sh build --docker

This builds the following components and packages them into a single Docker image:

ComponentDescription
ImmerseFrontend map and chart UI
WebServerHeavyAI web server
GEOS DSOsGeometry shared libraries
HeavyDBCore database engine
Docker imageFinal 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 a log directly:

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

5. Confirm the image

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

docker image ls

You should see two new images. For example:

REPOSITORY                              TAG       IMAGE ID       CREATED        SIZE
heavyai-ubuntu22.04-cuda-render-x86_64  10.0.0    3f9a1c2d8e4b   2 minutes ago  18.3GB
ghcr.io/heavyai/heavydb/core-build-...  latest    7a2b4d6e8f1c   3 days ago     12.1GB

Warning: The image whose name begins with core-build- is the build container used to compile HeavyAI — it does not run HeavyAI. Only the product image (e.g. heavyai-ubuntu22.04-cuda-render-x86_64:10.0.0) should be deployed to your production environment.

Note the full product image name and tag from your output — you will need it in Step 6.

6. Deployment

Update your existing docker-compose.yml with the new image name, then start the service.

Update docker-compose.yml

Open your existing docker-compose.yml and update the image: field:

services:
  heavyai:
    container_name: heavyai
    image: heavyai-ubuntu22.04-cuda-render-x86_64:10.0.0dev-20260929-d82ef84046
    volumes: 
      - /var/lib/heavyai:/var/lib/heavyai
    ports: 
      - "6273:6273"
      - "6274:6274"
      - "6276:6276"
      - "6278:6278"

Note: Only the image: value needs to change — all other settings in your docker-compose.yml (volumes, ports, environment, restart policy) can remain as-is.

If you built on the same machine where HeavyAI runs, apply the updated compose file and start the service now:

docker compose up -d

Export and transfer

If the build machine differs from the production host, save the image and transfer it:.

On the build machine:

# Export the image to a compressed archive
docker save heavyai-ubuntu22.04-cuda-render-x86_64:10.0.0 \
  | gzip > heavyai-ubuntu22.04-cuda-render-x86_64-10.0.0.tar.gz
# Transfer the image and updated compose file to the production host
rsync -avz --progress \
  heavyai-ubuntu22.04-cuda-render-x86_64-10.0.0.tar.gz \
  docker-compose.yml \
  user@YOUR_HEAVYAI_HOST:/opt/heavyai/

On the destination host:

# Load the image into Docker
docker load < /opt/heavyai/heavyai-ubuntu22.04-cuda-render-x86_64-10.0.0.tar.gz
# Start the service
cd /opt/heavyai
docker compose up -d

Note: A full HeavyAI image is typically 15–20 GB uncompressed. Ensure sufficient disk space on both machines before exporting. The --progress flag on rsync will show live transfer throughput.

7. Initial configuration (optional)

See Post-Installation Actions for steps to change the admin password, configure servers.json, enable TLS, and set up Mapbox/Google API keys in heavy.conf.

References