Project Setup and Environment Configuration

On-prem Deployment Guide (AWS)

Step 1: Download Installer Package from S3

Application/System: AWS S3 and EC2 VM

Goal: Obtain the hivel-onprem package (deployment scripts, Docker Compose files, configuration templates) on your VM.

On your EC2 VM, run:

cd /opt

# Download the package from S3
# Using AWS CLI 
aws s3 cp s3://hivel-on-prem-logs/hivel-agent-onprem-deploy/hivel-onprem.zip ./

# Extract the package
unzip hivel-onprem.zip
cd hivel-onprem

# Make deploy script executable
chmod +x deploy.sh

Verify: Run ls and confirm presence of: deploy.sh, config/, license/, services/, scripts/

Note: Receive your S3 bucket path or pre-signed URL from Hivel support.

If S3 access fails: "Access Denied" typically means your AWS credentials lack S3 read permissions. Confirm with Hivel support that your IAM credentials cover the installer bucket (not just ECR).

Step 2: Install License Files

Application/System: EC2 VM

Goal: Place Hivel-issued license files into the deployment package.

On your EC2 VM, run:

# Copy license files to the license directory
cp license_signed.json hivel-onprem/license/
cp hivel_onprem_public.pem hivel-onprem/license/

# Verify files exist
ls -l license/

Verify: Both license_signed.json and hivel_onprem_public.pem are present.

Environment Configuration

Step 1: Create and Configure Environment File

Application/System: EC2 VM text editor

Goal: Create the .env file containing all service configuration.

On your EC2 VM, run:

cd /opt/hivel-onprem

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

# Edit configuration
nano config/.env

Required configuration: Database variables (DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD) are mandatory. All services fail to start without them. Leave other template variables at their defaults unless Hivel support specifies otherwise.

Step 2: Configure RDS Credentials (Two-Phase Process)

Application/System: AWS RDS and EC2 VM

Phase 1: Root Credentials for Database Migration (First Time Only)

In config/.env, enter your RDS master credentials:

# ============================================
# Database Configuration (RDS) - Phase 1: Migration
# ============================================

# Your RDS endpoint (from AWS Console)
DB_HOST=your-rds-endpoint.ap-south-1.rds.amazonaws.com

# RDS port (usually 5432)
DB_PORT=5432

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

# RDS master/root username (for migration only)
DB_USER=postgres

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

If using AWS Secrets Manager: Retrieve master credentials from AWS Secrets Manager and use them here.

Important: Passwords with special characters ()[]$&|;#<>* or spaces must be enclosed in single quotes.

Special case: dollar signs ($): If your password contains $, write it as $$ (even inside single quotes), because Docker Compose interpolates $VAR variables.

Single quotes in password: Not allowed. If needed, redesign the password without literal single quotes.

Phase 2: Application User Credentials for Services (After Migration Completes)

After flyway-migration successfully completes, update config/.env with the application user:

# ============================================
# Database Configuration (RDS) - Phase 2: Services
# ============================================

# Your RDS endpoint (from AWS Console)
DB_HOST=your-rds-endpoint.ap-south-1.rds.amazonaws.com

# RDS 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 (if not customized):

• Username: <user>

• Password: <password>

To customize the application password:

1. Before running flyway-migration: Update password in scripts/flyway-migration/ config files

2. After migration: Update the same password in config/.env

3. Ensure both locations match

Password quoting rule: If your password contains special characters or spaces, use single quotes:

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

Step 3: Verify RDS Connectivity

Application/System: EC2 VM

Goal: Confirm the VM can reach RDS before running database migration.

On your EC2 VM, run:

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

# Test connection from EC2
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 insightly=# prompt with no errors.

Connection fails? See Troubleshooting: Database Connection Issues

If successful: Proceed to database migration.

Back to RDS Database Setup

ECR Access Configuration