> 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/self-managed-hivel-deployment/virtual-private-cloud/azure/hivel-on-premises-deployment-guide-azure/environment-configuration.md).

# Environment Configuration

On-Prem Deployment Guide (Azure)

## **Step 1: Create Environment File**

**Where to go:** Your VM in the hivel-onprem directory

```
cd /opt/hivel-onprem
 
# Copy template
cp config/.env.template config/.env
 
# Edit configuration
nano config/.env
```

## **Step 2: Configure Database Credentials**

> **Important:** Use a two-phase credential approach. Configure admin credentials first (for migration), then switch to application user credentials (for services).

### **Phase 1: Admin Credentials for Migration**

For flyway-migration only, use your PostgreSQL server admin credentials. Update these values in `config/.env`:

```
# ============================================
# Database Configuration (Azure PostgreSQL) - Phase 1: Migration
# ============================================
 
# Your Azure PostgreSQL server host (from Azure Portal)
DB_HOST=your-server.postgres.database.azure.com
 
# Port (usually 5432)
DB_PORT=5432
 
# Database name (must be "insightly")
DB_NAME=insightly
 
# Server admin username (for migration only)
DB_USER=postgres
 
# Server admin password (for migration only)
# Use single quotes if password contains special characters: ()[]$&|;#<>*
DB_PASSWORD='your_admin_password'

```

If credentials are stored in Azure Key Vault, retrieve the admin credentials before updating .env.

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

After flyway-migration completes successfully, update `config/.env` to use the application user. Flyway automatically creates this user:

```
# ============================================
# Database Configuration (Azure PostgreSQL) - Phase 2: Services
# ============================================
 
# Your Azure PostgreSQL server host (from Azure Portal)
DB_HOST=your-server.postgres.database.azure.com
 
# Port (usually 5432)
DB_PORT=5432
 
# Database name (must be "insightly")
DB_NAME=insightly
 
# Application user (created by flyway-migration)
DB_USER=<user>
 
# Application user password (default, can be customized)
# Default password: <password>
# Use single quotes if password contains special characters: ()[]$&|;#<>*
DB_PASSWORD='<password>'

```

Default application credentials created by flyway-migration:

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

#### **Customizing the Application Password**

If you want a different password for the application user:

1. Before running flyway-migration: Update the password in the flyway migration scripts/config
2. After migration: Update the password in `config/.env` to match

#### **Password Formatting**

* Passwords with special characters `()[]$&|;#<>*`: Must use single quotes Example: `DB_PASSWORD='Uxt2Z<XGvb0a7[4nc*zNJd)z#qGQ'`
* If password contains a literal `$`: Write it as `$$` inside single quotes (Docker Compose interpolates variables, so `$$` escapes to a literal `$`)
* Single quotes cannot appear inside the password itself (e.g., `pass'word` is not allowed), but you can enclose the entire password in single quotes

> Why single quotes? 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. They're only for bash's benefit.

***

## **Step 3: Test Database Connection**

**Where to go:** Your VM

Install the PostgreSQL client (if not already installed) and test the connection:

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

# Test connection from the VM (Azure requires SSL by default)
psql "host=$DB_HOST port=$DB_PORT dbname=$DB_NAME user=$DB_USER password=$DB_PASSWORD sslmode=require"
 
# 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 or connection errors.

**If it fails:** see Database connection issues in [Troubleshooting](/self-managed-hivel-deployment/virtual-private-cloud/azure/hivel-on-premises-deployment-guide-azure/troubleshooting.md).

**If connection succeeds:** You're ready to proceed to the next step.

**Next Step:** Database Migration

<br>

{% columns %}
{% column %} <a href="/self-managed-hivel-deployment/virtual-private-cloud/azure/hivel-on-premises-deployment-guide-azure/ecr-access-configuration.md" class="button primary" data-icon="backward">Back to ECR Access Configuration</a>
{% endcolumn %}

{% column %}

{% endcolumn %}

{% column %} <a href="/self-managed-hivel-deployment/virtual-private-cloud/azure/hivel-on-premises-deployment-guide-azure/database-migration.md" class="button primary" data-icon="forward">Database Migration</a>
{% endcolumn %}
{% endcolumns %}