TL;DR (AWS)

AWS Quick Deployment Guide

Deploy Hivel on your own AWS account using EC2 for compute and Amazon RDS for the database. This condensed guide covers the same steps in the same order without omitting any part of the deployment process. Refer to the full AWS Setup Guide for additional context, detailed explanations, or troubleshooting guidance.

Prerequisites

Before you start, confirm you have:

• An AWS account with permissions to create EC2 and RDS resources

• Hivel-issued AWS Access Key ID and Secret Access Key, scoped to Hivel's ECR

• An S3 bucket path or pre-signed URL for the hivel-onprem installer package

• Hivel license files: license_signed.json and hivel_onprem_public.pem

If you lack any of these, contact [e-mail] before starting. Deployment cannot complete without them.

Step 1: Provision an EC2 Instance

In AWS Console:

1. Launch a new EC2 instance with Ubuntu 22.04 LTS or later

2. Instance type: t3.xlarge (4 vCPU, 16GB RAM) minimum. For high integration or commit volume, consult Hivel before finalizing sizing

3. Storage: 50GB volume

4. Security group: allow inbound on ports 22, 80, 443, 3000, 4317 (if Claude is being integrated), and 5432

5. Note the instance's public and private IP address

6. SSH into the instance to confirm access

Step 2: Install Required Software

On EC2 VM:

# Update system and install postgres, unzip
sudo apt update && sudo apt upgrade -y
sudo apt install -y postgresql postgresql-contrib
sudo apt install -y unzip

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER

# Install Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

# Install AWS CLI
curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
unzip awscliv2.zip
sudo ./aws/install

# Install PostgreSQL client (needed to test RDS connectivity and create the database)
sudo apt install -y postgresql-client

# Verify installations
docker --version
docker-compose --version
aws --version
psql --version

Required versions: Docker >= 26.0, Docker Compose >= 2.25.0, any current AWS CLI v2.x. Log out and back in for the Docker group change to take effect.

If docker commands still ask for sudo, run newgrp docker or reboot the instance.

Step 3: Configure the AWS CLI

On EC2 VM:

aws configure
# AWS Access Key ID:     [Hivel-provided access key]
# AWS Secret Access Key: [Hivel-provided secret key]
# Default region name:   ap-south-1
# Default output format: json

# Verify
aws sts get-caller-identity

Expect a JSON object with your AWS account details. If it fails with "Unable to locate credentials," re-run aws configure and check cat ~/.aws/credentials.

Step 4: Provision RDS PostgreSQL

In AWS Console:

1. Go to RDS Console and create a PostgreSQL database with:

   • Engine: PostgreSQL 12 to 15

   • Instance class: db.t3.medium or larger

   • Storage: 20GB+ gp3

   • Master username: postgres (fixed, do not change)

   • Master password: choose a strong password and save it securely

2. Create a custom parameter group for your PostgreSQL version:

   • Set rds.force_ssl to 0 (this deployment uses network-level isolation as the security boundary)

   • Attach the parameter group to the RDS instance; reboot if AWS requires it

3. Note: RDS endpoint, port (usually 5432), master username, and master password

4. Configure the RDS security group for access only from your VM:

   • RDS Console → your database → Connectivity & security → click the security group

   • Add an inbound rule: Type PostgreSQL, Port 5432, Source your VM's security group ID

Expected result: RDS console shows status Available, and a connection test from the VM succeeds on port 5432.

Step 5: Create the insightly Database

On EC2 VM:

insightly is Hivel's fixed database name, not a placeholder to rename.

psql -h <your-rds-endpoint> -U <rds-username> -d postgres
CREATE DATABASE insightly;
\q

If you only have console access instead of network access to RDS, use RDS Console → your database → Query Editor → connect → run CREATE DATABASE insightly;.

Step 6: Download the Installer and License Files

On EC2 VM:

cd /opt

# Download the package from S3
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

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

# Verify
ls -l license/

Confirm deploy.sh, config/, license/, services/, and scripts/ are present. If S3 access fails with "Access Denied," confirm with Hivel support that your IAM credentials cover the installer bucket, not just ECR.

Step 7: Configure the Environment File: Phase 1 (Migration Credentials)

On EC2 VM:

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

Set these database variables to your RDS master credentials:

# 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)
DB_PASSWORD='your_rds_master_password'

DB_HOST, DB_PORT, DB_NAME, DB_USER, and DB_PASSWORD are mandatory; all services fail without them. Leave other template variables at their defaults unless Hivel support directs otherwise.

Passwords containing ()[]$&|;#<>* or spaces must be wrapped in single quotes. A literal $ must be written as $$ even inside single quotes because Docker Compose interpolates $VAR. A literal single quote in the password is not allowed; choose a different password if needed.

Step 8: Verify RDS Connectivity

On EC2 VM:

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: an insightly=# prompt with no errors. Do not continue until this works.

Step 9: Test ECR Access

On EC2 VM:

Hivel's Docker images are stored in Amazon ECR at 730335373269.dkr.ecr.ap-south-1.amazonaws.com. Your AWS CLI credentials are scoped specifically to this registry.

aws ecr get-login-password --region ap-south-1 | \
  docker login --username AWS --password-stdin \
  730335373269.dkr.ecr.ap-south-1.amazonaws.com

Expected: Login Succeeded. deploy.sh handles ECR authentication automatically from here on.

Using your own ECR instead is an advanced path requiring you to push Hivel's images to your own repositories and update image URLs in services/vm/docker-compose.yml plus ECR_REGISTRY/AWS_REGION variables in deploy.sh. Only do this if your organization requires images in your own infrastructure.

Step 10: Run the Database Migration

On EC2 VM:

This runs once only, before any other services start. It initializes the entire database.

cd /opt/hivel-onprem
./deploy.sh --service flyway-migration

Wait 1 to 2 minutes for completion, then verify:

# Check migration logs
docker logs flyway-migration

# Check exit code (0 = success)
docker inspect flyway-migration --format='{{.State.ExitCode}}'

# Check container status
docker ps -a | grep flyway-migration

Success: exit code 0, logs containing "Successfully applied X migration(s)" and "user <user> created", container status "Exited (0)". Do not proceed if migration failed or rerun migration on an already-initialized database.

Step 11: Switch the Environment File to Application Credentials: Phase 2

On EC2 VM:

nano config/.env

Update these values:

DB_USER=<user>
DB_PASSWORD='<password>'  # Default password (or your custom password)

The default application username and password are provided separately by Hivel. If you customized the password before running the migration, use that same password here. All services from this point on connect using this application user, not the RDS master account.

Step 12: Deploy All Services

On EC2 VM:

cd /opt/hivel-onprem
./deploy.sh --vm

All available deploy.sh commands:

./deploy.sh --all       # Deploy all services
./deploy.sh --vm        # Deploy VM services only
./deploy.sh --service <service-name>  # Deploy specific service
./deploy.sh --status    # Check service status
./deploy.sh --health    # Check service health
./deploy.sh --logs      # View logs
./deploy.sh --logs <service-name>     # View logs for one service
./deploy.sh --start     # Start services
./deploy.sh --stop      # Stop services
./deploy.sh --restart   # Restart services
./deploy.sh --update    # Update services (pull latest images)
./deploy.sh --list      # List all services
./deploy.sh --help      # Show help

For specific service guidance, contact [e-mail]. Deploying with Docker Compose directly is available as an advanced alternative if you need custom orchestration or staged rollouts.

Step 13: Set Up Log Rotation

On EC2 VM:

cd /opt/hivel-onprem
sudo ./scripts/setup-log-rotation.sh

# Verify
sudo crontab -l
ls -la /var/log/hivel/

This creates /var/log/hivel/, adds a daily cron job at midnight, and configures rotation for all Docker containers with 7-day retention. Logs live at /var/log/hivel/<service-name>/<service-name>-YYYY-MM-DD.log.

Step 14: Verify the Deployment

On EC2 VM, then a browser:

# Check all containers
docker ps
./deploy.sh --health

# Test service endpoints
curl http://localhost:80/health            # API Gateway
curl http://localhost:8095/health          # Auth Service
curl http://localhost:8082/hivelapi/health # Insightly Service
curl http://localhost:3000                 # UI

All containers should show Up/healthy, and each endpoint should return a healthy response.

Then access the app via one of these options:

• Direct EC2 IP (testing only, no HTTPS, IP changes on restart): http://<vm-public-ip>:3000

• Application Load Balancer (stable, HTTPS not yet configured): create an ALB in AWS Console, configure a target group pointing to the VM on ports 80 and 3000, configure listener rules

• Route53 + ALB (production recommended): create the ALB as above, create a Route53 hosted zone for your domain, create an A record (alias) pointing to the ALB, configure an SSL/TLS certificate on the ALB, access via https://your-domain.com

Deployment is complete when: all containers are healthy, every endpoint returns healthy, the UI loads with no console errors, and at least one integration (Jira/GitHub/GitLab) is connected and shows data after Step 16.

Step 15 (Optional but Recommended): Enable HTTPS with Caddy

In AWS Console, then on EC2 VM:

Modern browsers restrict crypto.randomUUID, used on the sign-up page, to secure contexts (HTTPS or localhost). Accessing the UI over plain HTTP will fail sign-up.

In Route53: create an A record pointing your subdomain (e.g., hivel.yourcompany.com) at the VM's public IP. Use an Elastic IP so the address doesn't change on restart.

# Verify DNS has propagated
dig +short hivel.yourcompany.com

In EC2 security group: add inbound rules for port 80 (source 0.0.0.0/0, required for Let's Encrypt's HTTP-01 validation) and port 443 (source 0.0.0.0/0 or your office/VPN CIDR).

On EC2 VM:

mkdir -p ~/caddy && cd ~/caddy

cat > Caddyfile <<'EOF'
hivel.yourcompany.com {
  reverse_proxy localhost:3000
}
EOF

docker run -d --name caddy --restart unless-stopped --network host \
  -v $(pwd)/Caddyfile:/etc/caddy/Caddyfile \
  -v caddy_data:/data \
  caddy:2

# Verify
docker ps | grep caddy
docker logs -f caddy

Wait for a log line confirming the certificate was obtained, then open https://hivel.yourcompany.com in a browser. Expect a trusted certificate with no warnings.

No domain yet? Use a temporary self-signed certificate for testing only; see the full DNS Setup guide's Option B, then upgrade once you have a domain.

Step 16: Sign Up and Connect Integrations

In a browser, at the Hivel UI:

1. Go to http://<vm-public-ip>:3000/signup (or your HTTPS domain), enter your email, create a password, and complete email verification

2. Log in. You'll be redirected to the Company Profile Creation page

3. Fill in your organization's details, select an approval method for new users, and continue to the Integration page

4. Connect the tools you need:

   • GitLab: your GitLab domain URL, the access-token user's name and email, your GitLab access token, API version /api/v4. Verify under Settings > Repository; you should see repositories being analyzed

   • Jira: your Jira URL (Cloud: https://yourcompany.atlassian.net), the access-token user's name and email, your Jira access token, API version /rest/api/3/

   • SonarQube: your SonarQube instance URL and access token

See Integrations for the full list of supported integrations.

🔗Integrations

Initial data sync time depends on the volume of historical data. For issues during setup, see Troubleshooting or contact [e-mail].

Troubleshooting

Deployment complete. See the full AWS Setup Guide for detailed instructions.

Back to AWS

Hivel On-Premises Deployment Guide (Azure)