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.

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

Next Step: Database Migration

Back to ECR Access Configuration

Database Migration