> 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/aws/hivel-on-premises-deployment-guide-aws/project-setup-and-environment-configuration.md).

# 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](https://docs.hivel.ai/self-managed-hivel-deployment/virtual-private-cloud/aws/hivel-on-premises-deployment-guide-aws/troubleshooting)

**If successful:** Proceed to database migration.

\ <br>

{% columns %}
{% column %} <a href="/self-managed-hivel-deployment/virtual-private-cloud/aws/hivel-on-premises-deployment-guide-aws/rds-database-setup.md" class="button primary" data-icon="backward">Back to RDS Database Setup</a>
{% endcolumn %}

{% column %}

{% endcolumn %}

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