> 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/tl-dr-aws.md).

# 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](https://docs.hivel.ai/self-managed-hivel-deployment/virtual-private-cloud/aws) 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 <support@hivel.ai> 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:**

```bash
# 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.&#x20;

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

#### Step 3: Configure the AWS CLI

**On EC2 VM:**

```bash
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.

```bash
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:**

```bash
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
```

```bash
# 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:**

```bash
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:**

```bash
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.

```bash
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.

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

Wait 1 to 2 minutes for completion, then verify:

```bash
# 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:**

```bash
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:**

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

All available `deploy.sh` commands:

```bash
./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 <support@hivel.ai>. 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:**

```bash
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:**

```bash
# 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.

```bash
# 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:**

```bash
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](https://docs.hivel.ai/integrations) for the full list of supported integrations.

{% content-ref url="/pages/0DjYyMycz6IX42k8sXub" %}
[Integrations](/integrations.md)
{% endcontent-ref %}

Initial data sync time depends on the volume of historical data. For issues during setup, see [Troubleshooting](https://docs.hivel.ai/self-managed-hivel-deployment/virtual-private-cloud/aws/hivel-on-premises-deployment-guide-aws/troubleshooting) or contact <support@hivel.ai>.

{% content-ref url="/pages/iWDIHuDALOlX8eMpPQ7S" %}
[Troubleshooting](/self-managed-hivel-deployment/virtual-private-cloud/aws/hivel-on-premises-deployment-guide-aws/troubleshooting.md)
{% endcontent-ref %}

**Deployment complete.** See the full [AWS Setup Guide](https://docs.hivel.ai/self-managed-hivel-deployment/virtual-private-cloud/aws) for detailed instructions.

{% columns %}
{% column %} <a href="/self-managed-hivel-deployment/virtual-private-cloud/aws.md" class="button primary" data-icon="backward">Back to AWS</a>
{% endcolumn %}

{% column %}

{% endcolumn %}

{% column %} <a href="/self-managed-hivel-deployment/virtual-private-cloud/azure/hivel-on-premises-deployment-guide-azure.md" class="button primary" data-icon="forward">Hivel On-Premises Deployment Guide (Azure)</a>
{% endcolumn %}
{% endcolumns %}