# Overview

HEAVY.AI has minimal configuration requirements with a number of additional configuration options. This topic describes the required and optional configuration changes you can use in your HEAVY.AI instance.

{% hint style="warning" %}
In release 4.5.0 and higher, HEAVY.AI requires that all configuration flags used at startup match a flag on the HEAVY.AI server. If any flag is misspelled or invalid, the server does not start. This helps ensure that all settings are intentional and will not have an unexpected impact on performance or data integrity.
{% endhint %}

## Storage Directory

Before starting the HEAVY.AI server, you must initialize the persistent `storage` directory. To do so, create an empty directory at the desired path, such as `/var/lib/heavyai`.

1. Create the environment variable `$HEAVYAI_BASE`.

```sql
export HEAVYAI_BASE=/var/lib/heavyai
```

2\. Then, change the owner of the directory to the user that the server will run as ($HEAVYAI\_USER):

```
sudo mkdir -p $HEAVYAI_BASE sudo chown -R $HEAVYAI_USER $HEAVYAI_BASE
```

where $HEAVYAI\_USER is the system user account that the server runs as, such as `heavyai`, and $HEAVYAI\_BASE is the path to the parent of the HEAVY.AI server storage directory.

3\. Run $HEAVYAI\_PATH/bin/initheavy with the storage directory path as the argument:

```
$HEAVYAI_PATH/bin/initheavy $HEAVYAI_BASE/storage
```

## Configuring a Custom Heavy Immerse Subdirectory

Immerse serves the application from the root path (/) by default. To serve the application from a sub-path, you must modify the $HEAVYAI\_PATH/frontend/app-config.js file to change the IMMERSE\_PATH\_PREFIX value. The Heavy Immerse path must start with a forward slash (/).

## Configuration File

The configuration file stores runtime options for your HEAVY.AI servers. You can use the file to change the default behavior.

The heavy.conf file is stored in the $HEAVYAI\_BASE directory. The configuration settings are picked up automatically by the `sudo systemctl start heavydb` and `sudo systemctl start heavy_web_server` commands.

Set the flags in the configuration file using the format `<flag> = <value>`. Strings must be enclosed in quotes.

The following is a sample configuration file. The entry for `data` path is a string and must be in quotes. The last entry in the first section, for `null-div-by-zero`, is the Boolean value `true` and does not require quotes.

```bash
port = 6274 
http-port = 6278
data = "/var/lib/heavyai/storage"
null-div-by-zero = true

[web]
port = 6273
frontend = "/opt/heavyai/frontend"
servers-json = "/var/lib/heavyai/servers.json"
enable-https = true
```

To comment out a line in heavy.conf, prepend the line with the pound sign (**#**) character.

{% hint style="danger" %}
For encrypted backend connections, if you do not use a configuration file to start the database, Calcite expects passwords to be supplied through the command line, and calcite passwords will be visible in the processes table. If a configuration file is supplied, then passwords must be supplied in the file. If they are not, Calcite will fail.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.heavy.ai/v8.3.0/installation-and-configuration/config-parameters/overview.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.