> For the complete documentation index, see [llms.txt](https://docs.hivel.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hivel.ai/archive/generic/hivel-on-premises-deployment-guide-generic/6.-environment-configuration.md).

# 6. Environment Configuration

On-Prem Deployment Guide (Generic)

### Step 1: Create the Environment File

Goal: create a working config/.env file on both servers, ready for database credentials.

On both VM1 and VM2:

```
cd /opt/docker-onprem-installer

# Copy template
cp config/.env.template config/.env

# Edit configuration
nano config/.env
```

**Required vs. optional values:** the database variables covered in Step 2 below (DB\_HOST, DB\_PORT, DB\_NAME, DB\_USER, DB\_PASSWORD) are required - deployment will not work without them. config/.env.template may also include other, optional variables with working defaults (e.g. non-database service settings) that most deployments don't need to change.

The DB\_\* variables covered in Step 2 are the only configuration you need to change in config/.env. Every other variable in config/.env.template is either optional or already pre-set with a working default, so this guide does not maintain a separate variable-by-variable inventory table - leave the rest of the file as shipped unless Hivel support directs you otherwise.

### Step 2: Configure Database Credentials

**Important:** Two-Phase Credential Configuration is required - see below.

#### Phase 1: Root Credentials for Migration

For flyway-migration (first time only), use the database's root/master credentials:

```
# ============================================
# Database Configuration - Phase 1: Migration
# ============================================

# Your database endpoint
DB_HOST=your-db-endpoint.example.com

# Database port (usually 5432)
DB_PORT=5432

# Database name (must be "insightly")
DB_NAME=insightly

# Database master/root username (for migration only)
DB_USER=your_db_master_username

# Database master/root password (for migration only)
# Use single quotes if password contains special characters: ()[]$&|;#<>*
DB_PASSWORD='your_db_master_password'
```

If your credentials live in a secrets manager: retrieve the master credentials from it and use these root credentials for flyway-migration only.

#### Phase 2: Application User Credentials for Services

After flyway-migration completes successfully, update .env to use the application user:

```
# ============================================
# Database Configuration - Phase 2: Services
# ============================================
DB_HOST=your-db-endpoint.example.com
DB_PORT=5432
DB_NAME=insightly

# Application user (created by flyway-migration)
DB_USER=<user>

# Application user password (default, can be customized)
# Default password: <password>
DB_PASSWORD='<password>
```

Default Application Credentials:

* Username: \<user>
* Password: \<password> (default, can be customized)

Customizing the application password:

* Before running flyway-migration: update the password in the flyway migration scripts/config
* After migration: update the password in config/.env to match
* Important: if you change the password, ensure it's updated in both places

#### Password Quoting

Passwords with special characters (()\[]$&|;#<>\*) or spaces: must use single quotes

```
DB_PASSWORD='Uxt2Z<XGvb0a7[4nc*zNJd)z#qGQ'
```

**Why?** The deployment script sources the .env file, and bash interprets special characters as commands. Single quotes prevent this - the quotes are not passed to Docker, only used for bash's benefit. Separately, if the password contains a literal $, write it as $$ even inside the single quotes - Docker Compose interpolates ${...}/$VAR when it reads .env for the containers, so an unescaped $ there is misread as a variable reference rather than a literal character.

> Single quotes (`'`) are not allowed within the password itself, example: ('pass'word'). However, you can enclose the entire password in single quotes (`'password'`).

### Step 3: Test the Database Connection

**Goal:** confirm both servers can reach the database before running migration.

On both VM1 and VM2:

```
# Install PostgreSQL client
sudo apt update && sudo apt install -y postgresql-client

# Test connection from the server
psql -h $DB_HOST -U $DB_USER -d $DB_NAME -p $DB_PORT

# Or using environment variables
export PGPASSWORD='your_password'
psql -h $DB_HOST -U $DB_USER -d $DB_NAME -p $DB_PORT
```

**Expected result:** a psql prompt (insightly=#) with no password/connection error.

**If it fails:** see Database connection issues in [Troubleshooting](/archive/generic/hivel-on-premises-deployment-guide-generic/11.-troubleshooting.md).

If connection succeeds, you're ready to proceed.

**Next step:** Database Migration - initialize the schema and application user.

<br>

{% columns %}
{% column %} <a href="/archive/generic/hivel-on-premises-deployment-guide-generic/5.-database-and-project-setup.md" class="button primary" data-icon="backward">Database and Project Setup</a>
{% endcolumn %}

{% column %}

{% endcolumn %}

{% column %} <a href="/archive/generic/hivel-on-premises-deployment-guide-generic/7.-database-migration.md" class="button primary" data-icon="forward">Database Migration</a>
{% endcolumn %}
{% endcolumns %}