Environment Configuration

Step 1: Create the .env File

On the host, run:

cd /opt/hivel-onprem
cp config/.env.template config/.env
nano config/.env

Step 2: Configure Phase 1 Database Credentials (For Migration)

Add the superuser credentials. These are used only during the migration step:

DB_HOST=<host-running-postgres-private-ip>
DB_PORT=5432
DB_NAME=insightly
DB_USER=postgres
DB_PASSWORD='your_superuser_password'

Step 3: Configure Phase 2 Database Credentials (After Migration)

After the migration succeeds, update the .env file to use the application user credentials:

DB_HOST=<host-running-postgres-private-ip>
DB_PORT=5432
DB_NAME=insightly
DB_USER=postgres
DB_PASSWORD='<APPLICATION_USER_PASSWORD>'

NOTE: <user> is created automatically by flyway-migration, with a default password Hivel provides separately - change it before production, and never commit a real password to source control.

Customizing the Application Password:

If you want to use a different password for the application user:

1. Before migration: Update the password in the Flyway migration scripts/config

2. After migration: Update config/.env with the new password

3. Ensure the password is consistent in both locations

Step 4: Apply Password Quoting Rules

Passwords containing special characters require single quotes. Use these rules:

Rule 1: Any password containing ()[]$&|;#<>* or spaces must be single-quoted:

DB_PASSWORD='P@ss!w0rd(2024)#'

Rule 2: If the password contains a literal $, escape it as $$ even inside single quotes (Docker Compose interpolates ${...} variables):

DB_PASSWORD='P@$$word2024'

Rule 3: Single quotes (') cannot appear within the password itself. Example - this is invalid: DB_PASSWORD='pass'word'. Instead, enclose the entire password: DB_PASSWORD='password'.

Step 5: Test Database Connection

Verify the connection from the host:

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

psql -h $DB_HOST -U $DB_USER -d $DB_NAME -p $DB_PORT
# or
export PGPASSWORD='your_password'
psql -h $DB_HOST -U $DB_USER -d $DB_NAME -p $DB_PORT

When prompted, enter the superuser password.

Success: A psql prompt (insightly=#) appears with no errors Failure: Check the host/port/credentials and confirm PostgreSQL is running and accepting connections

Back to Registry Access Configuration

Database Migration