> This page is for HEAVY.AI. > 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. # Post Installation Actions After deploying HEAVY.AI — whether via the [Build from Source](https://docs.nvidia.com/heavyai/installation-and-configuration/installation/build-from-source) path or the [Migration from Legacy* *Enterprise Edition](https://docs.nvidia.com/heavyai/installation-and-configuration/installation/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*](http://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: ```null 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*](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 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: ```null 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`: ```null [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: ```null [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: ```json [   {     "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: ```shell 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):** ```shell 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):** ```shell /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-:` ```shell 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: ```shell sudo ln -sfn /opt/heavyai-10.0.0-ubuntu22.04-x86_64 /opt/heavyai ``` 3. Run the systemd installation script from `/systemd` to register service definitions: ```shell cd /opt/heavyai/systemd sudo ./install_heavyai_systemd.sh ``` 4. Enable and start the `heavydb` and `heavy_web_server` systemd services: ```shell 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: ```shell 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. ```shell 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 ```shell 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. ```shell 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. ```shell [ { "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 | **Symptom** | **Likely cause** | | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Blank or gray map | `mapbox-token` is missing or invalid in `heavy.conf`, the service was not restarted after the configuration change, token URL restrictions block the production host, or a Mapbox billing or scope issue. | | Zoom-to search does nothing | `google-api-key` is missing in `heavy.conf`, the service was not restarted after the change, the Geocoding API is not enabled on the project, or billing is disabled. | | No zoom-to search box | `ui/disable_map_geocoder` is set to `true` in `feature_flags`. | | HTTPS connection errors after enabling TLS | TLS may already be terminated upstream. Disable `enable-https` in `heavy.conf` if a proxy or load balancer handles SSL in front of HeavyAI. | | Login form not appearing | `"password"` is set in `servers.json` causing auto-login. Remove it to present the login form. | | Custom logo not appearing | Logo URLs must be browser-accessible `http(s)` URLs. Filesystem paths are not supported. | --- ## References * [Configuration Parameters Overview](https://docs.nvidia.com/heavyai/installation-and-configuration/config-parameters/overview) * [Configuration Parameters for HEAVY.AI Web Server](https://docs.nvidia.com/heavyai/installation-and-configuration/config-parameters/configuration-parameters-for-heavy.ai-web-server) * [Using Services](https://docs.nvidia.com/heavyai/installation-and-configuration/services-and-utilities/services) * [Using Utilities](https://docs.nvidia.com/heavyai/installation-and-configuration/services-and-utilities/utilities) * [HeavyAI Immerse Customization Guide](https://docs.nvidia.com/heavyai/immerse/customization) — servers.json reference, feature flags, UI keys, branding, custom basemaps * [Mapbox access tokens](https://docs.mapbox.com/help/diagnostics/how-to-use-mapbox-tokens/) * [Google Geocoding API](https://developers.google.com/maps/documentation/geocoding/overview)