> 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/archive/generic/hivel-on-premises-deployment-guide-generic/5.-database-and-project-setup.md).

# 5. Database and Project Setup

On-Prem Deployment Guide (Generic)

Hivel requires a PostgreSQL database. Use a managed PostgreSQL service on your chosen cloud (Amazon RDS, Azure Database for PostgreSQL, Cloud SQL for PostgreSQL) or a self-hosted PostgreSQL instance in your own data center.

### Step 1: Provision the Database

**Goal:** have a running PostgreSQL instance, reachable from both VM1 and VM2, before continuing.

* Engine: PostgreSQL 12 through 15
* Instance class / server size: equivalent to db.t3.medium or larger (2 vCPU / 4GB RAM minimum)
* **Storage:** 20GB+ SSD-backed
* Master/root username: **Master Username:&#x20;**<mark style="color:$primary;">**postgres**</mark> (Use `postgres` as the username. This value is fixed and must not be changed).
* Master/root password: choose a strong password and record it securely

This range reflects the versions this deployment has actually been tested against - versions outside 12–15 are not supported at this time.

**Configure the DB Parameter Group:**

* Create a custom DB parameter group compatible with your PostgreSQL version.
* Set `rds.force_ssl` to `0`.
* Attach the parameter group to the RDS database instance.
* Reboot the RDS instance if AWS indicates that a reboot is required.

Note the following details once provisioned:

* Database endpoint / hostname (e.g. mydb.xxxxx.rds.amazonaws.com, mydb.postgres.database.azure.com, or your internal hostname)
* Port (usually 5432)
* Master/root username
* Master/root password

Set up a backup routine for this database before going to production - see Backup and Restore.

### Using a Secrets Manager (Optional)

If your database credentials are stored in a secrets manager (AWS Secrets Manager, Azure Key Vault, GCP Secret Manager, HashiCorp Vault, or similar):

#### 1. For Flyway Migration (First Time Only)

* You must use the root/master credentials to run flyway-migration
* Flyway needs elevated privileges to create database schemas, tables, and users
* Use the database's master username and password in the .env file for migration

#### 2. After Migration Completes

* Flyway will create the application user: \<user>
* Default password: \<password> (can be customized)
* Update the .env file to use \<user> credentials for all services
* This is the recommended approach for production (least privilege)

#### 3. Two-Phase Credential Approach

* **Phase 1 (Migration):** use root/master credentials → run flyway-migration
* **Phase 2 (Services):** switch to \<user> credentials → deploy services

Why? Root credentials have full database privileges needed for initial setup. After migration, use the application user with limited privileges for better security. (This is the same least-privilege pattern referenced again in Security and Secrets - it isn't repeated there, just cross-referenced.)

### Step 2: Configure Network Access to the Database

Critical: the database must be reachable from both VM1 and VM2.

1. In your database's networking/connectivity settings, open its firewall or security group
2. Add an inbound rule allowing PostgreSQL (port 5432) from VM1's address or security group
3. Add another inbound rule allowing PostgreSQL (port 5432) from VM2's address or security group

Cloud-specific equivalents: AWS uses RDS Security Groups, Azure uses firewall rules on the PostgreSQL server resource, GCP uses authorized networks on Cloud SQL, and on-prem PostgreSQL uses pg\_hba.conf plus host firewall rules.

**Expected result:** a psql connection from both VM1 and VM2 succeeds (tested in Environment Configuration below).

**If it fails:** see Database connection issues in [Troubleshooting](/archive/generic/hivel-on-premises-deployment-guide-generic/11.-troubleshooting.md).

### Step 3: Create the Database Manually

You must create the "insightly" database before deployment.

#### Option A: Using psql

```
# Connect to the database
psql -h <your-db-endpoint> -U <db-username> -d postgres

# Create the database
CREATE DATABASE insightly;

# Exit
\q
```

#### Option B: Using Your Cloud Provider's Query Console

Most managed database consoles (AWS RDS Query Editor, Azure Query Editor, Cloud SQL Studio) provide a browser-based query tool. Connect and run:

```
CREATE DATABASE insightly;
```

Next step: Project Setup - download the Hivel deployment package onto both servers.

## Project Setup

The docker-onprem-installer package is distributed via Hivel's own S3 bucket, independent of which cloud your infrastructure runs on. It contains the deployment scripts, Docker Compose files, and configuration templates for your environment - it does not contain your license or credentials, which you add separately below.

### Step 1: Download the Project Package

**Goal:** get the docker-onprem-installer package extracted and ready on both VM1 and VM2.

On VM1:

```
cd /opt

# Download the package from Hivel's S3 bucket
# Option 1: Using AWS CLI (if you have access)
aws s3 cp s3://hivel-onprem-installer/docker-onprem-installer.zip ./

# Option 2: Using wget/curl (if you have a pre-signed URL from Hivel)
wget s3://hivel-onprem-installer/docker-onprem-installer.tar.gz -O docker-onprem-installer.tar.gz

# Extract the package
tar -xzf docker-onprem-installer.tar.gz
cd docker-onprem-installer

# Make deploy script executable
chmod +x deploy.sh
```

On VM2 (same steps):

```
cd /opt
aws s3 cp s3://hivel-onprem-installer/docker-onprem-installer.tar.gz ./
# or: wget <download-url-from-hivel> -O docker-onprem-installer.tar.gz

tar -xzf docker-onprem-installer.tar.gz
cd docker-onprem-installer
chmod +x deploy.sh
```

> Note: You will receive the S3 bucket path or a pre-signed download URL from Hivel support.

**Expected result:** ls docker-onprem-installer shows deploy.sh, config/, license/, services/, and scripts/ on both servers.

**If it fails:** an S3 AccessDenied error usually means the AWS credentials configured in AWS CLI Configuration aren't the ones with S3 download access - confirm with Hivel support which credential set is meant for S3 vs. ECR.

### Step 2: Add License Files

On both VM1 and VM2:

```
# Copy license files to the license directory
cp license/license_signed.json license/
cp license/hivel_onprem_public.pem license/

# Verify files exist
ls -l license/
```

**Expected result:** ls -l license/ lists both license\_signed.json and hivel\_onprem\_public.pem.

**Next step:** Environment Configuration - configure the .env file both servers will use.

<br>

{% columns %}
{% column %} <a href="/archive/generic/hivel-on-premises-deployment-guide-generic/4.-aws-cli-configuration-hivel-ecr-access.md" class="button primary" data-icon="backward">AWS CLI Configuration (Hivel ECR Access)</a>
{% endcolumn %}

{% column %}

{% endcolumn %}

{% column %} <a href="/archive/generic/hivel-on-premises-deployment-guide-generic/6.-environment-configuration.md" class="button primary" data-icon="forward">Environment Configuration</a>
{% endcolumn %}
{% endcolumns %}