Post Installation Actions

After deploying HEAVY.AI — whether via the Build from Source path or the Migration from Legacy Enterprise Edition path — complete the following actions before going live. None of these are strictly required for a functional installation, but all are strongly recommended for security and usability.

Manage API Keys

Immerse requires two API keys for full map chart functionality: a Mapbox access token and a Google Maps Geocoding API key.

Obtain a Mapbox Access Token

Mapbox provides basemap tiles for pointmap, choropleth, linemap, and other geo charts.

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 and add it to heavy.conf 

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 vendor-supplied default.

Offline alternative: If you cannot or do not want to use Mapbox, leave mapbox-token out of heavy.conf and set "offline": true in servers.json to use built-in country-outline basemaps instead.

Obtain a Google Maps Geocoding API key

The Google Maps Geocoding API powers the zoom-to address search box on map charts.

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 appropriate for your IT policy:
   • Under Application restrictions, HTTP referrer restrictions are generally preferable to IP restrictions for browser-side keys — the key is used directly within the end user’s browser, so any IP-based restrictions must account for the full range of your users’ client IP addresses rather than server IPs:

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.
7. Add the key to heavy.conf as shown above.

Offline alternative: Leave google-api-key out of heavy.conf and set "ui/enable_local_geocoder": true in feature_flags (inside servers.json) to use the HeavyAI /geocoder endpoint (requires server-side geocoder support).

Configure API keys in heavy.conf

Both API keys are set in the [web] section of heavy.conf:

[web]
mapbox-token = "YOUR_MAPBOX_TOKEN"
google-api-key = "YOUR_GOOGLE_API_KEY"

Restart the service after editing heavy.conf for changes to take effect:

Configure servers.json

Immerse’s default connection behavior, feature flags, UI element visibility, and branding are all controlled through a servers.json file.

Step 1: Reference servers.json in heavy.conf

In the [web] section of heavy.conf, add:

[web]
servers-json = "/var/lib/heavyai/servers.json"

Step 2: Create servers.json

Create servers.json in your storage directory. At minimum, set the default database connection:

[
  {
    "database": "heavyai",
    "host": "localhost",
    "port": "6273",
    "protocol": "http",
    "username": "admin"
  }
]

Installing libgeos

In order to use ST_* SQL functions, you will need to have the libgeos installation package.  There are a few possible scenarios based on your use case:

1. If you built heavydb from source, the dependency container build process creates a libgeos package for you.  In order to install it, you can simply unpack the generated archive to the correct location as below:

cd /var/lib/heavyai
mkdir libgeos
cd libgeos
tar xvf $WORKSPACE/heavydb/build/components/heavydb-libgeos-ubuntu22.04-x86_64.tar.xz

2. If you are migrating from an old version of HeavyAI, you likely already have them installed in this exact location. Any version previously used with HeavyDB 8.4-9.0 will still work.
3. If you are not using an ST_* database functions, you are not required to have the libgeos libraries installed.
4. You can manually compile libgeos libraries if required.

Change the Admin Password

The default admin password (HyperInteractive) must be changed before exposing HeavyAI to any users.

Via Immerse: Log in as admin using the default password, then navigate to Admin Portal → Users → admin → Edit and set a new password. You can also add and manage additional users from this interface.

Via heavysql (Docker):

docker compose exec heavyai \
  /opt/heavyai/bin/heavysql \
  -u admin -p HyperInteractive \
  --db heavyai \
  -c "ALTER USER admin (password='your-new-password');"

Via heavysql (systemd):

<HEAVYAI_PATH>/bin/heavysql \
  -u admin -p HyperInteractive \
  --db heavyai \
  -c "ALTER USER admin (password='your-new-password');"

Launch Configurations

HeavyAI can be configured to startup automatically using either Docker or your host operating system. Below is some guidance for initialization in different scenarios, as well as reference configurations:

Bare-Metal Installation

For bare-metal deployments without Docker, extract the HeavyAI release archive to your target path (typically /opt/heavyai) and configure systemd services using the provided installation script.

1. Extract the binary package to /opt/heavyai-<version>:

sudo tar xvf heavyai-10.0.0-ubuntu22.04-x86_64.tar.gz -C /opt

2. Create or update the symbolic link /opt/heavyai to point to the active version directory:

sudo ln -sfn /opt/heavyai-10.0.0-ubuntu22.04-x86_64 /opt/heavyai

3. Run the systemd installation script from <HEAVYAI_PATH>/systemd to register service definitions:

cd /opt/heavyai/systemd
sudo ./install_heavyai_systemd.sh

4. Enable and start the heavydb and heavy_web_server systemd services:

sudo systemctl enable --now heavydb heavy_web_server

By using the /opt/heavyai symlink, systemd service files remain static across platform upgrades. During an upgrade, update the symlink to the new directory version and restart services without reinstalling unit files:

sudo ln -sfn /opt/heavyai-new-version /opt/heavyai
sudo systemctl restart heavydb heavy_web_server

Docker Compose Installation 

Single Container

For basic deployments, HeavyAI can be run within a single Docker container containing both heavydb and heavy_web_server services managed together.

version: "3.7"
services:
  heavyai:
    container_name: heavyai
    image: heavyai-ubuntu22.04-cuda-render-x86_64:latest
    volumes:
      - /var/lib/heavyai:/var/lib/heavyai
    ports:
      - "6273:6273"
      - "6274:6274"
      - "6278:6278"
      - "6276:6276"
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

Example minimal docker-compose.yml file

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

Example minimal heavy.conf file

See configuration parameters for heavydb, heavy web server.

port = 6274
http-port = 6278
calcite-port = 6279
read-only = false
verbose = false
allowed-import-paths = ["/var/lib/heavyai/import", "/tmp"]
[web]
port = 6273
servers-json = "/var/lib/heavyai/servers.json"
mapbox-token ="pk. ... bQ"
google-api-key = "AIza ... LBcs"
[iq]
disabled = true

Example minimal servers.json file

See HeavyImmerse Customization.

[
  {
    "database": "heavyai",
    "host": "localhost",
    "port": "6273",
    "protocol": "http"
    
  }
  "feature_flags": {
    "ui/default_theme": "dark",
    "ui/dashboard_tabs": true,
    "ui/enable_auto_dashboard_refresh": true,
    "ui/enable_map_exports": true,
    "ui/enable_joins": true
    }
]

Troubleshooting

References

• Configuration Parameters Overview
• Configuration Parameters for HEAVY.AI Web Server
• Using Services
• Using Utilities
• HeavyAI Immerse Customization Guide — servers.json reference, feature flags, UI keys, branding, custom basemaps
• Mapbox access tokens
• Google Geocoding API