TL;DR (Azure)

Azure Quick Deployment Guide

Deploy Hivel on your own Azure account using a Virtual Machine for compute and Azure Database for PostgreSQL (Flexible Server) 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 Azure Setup Guide for additional context, detailed explanations, or troubleshooting guidance.

Prerequisites

Important: Your VM and database run on Azure, but Hivel's Docker images and installer package are distributed via AWS (ECR and S3). You need both Azure CLI and AWS CLI, plus credentials for both platforms, to complete this guide.

Before you start, confirm you have:

• An Azure subscription with Contributor role (or equivalent permissions)

• 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 Azure Virtual Machine

In Azure Portal:

1. Create a new Virtual Machine with:

   • Image: Ubuntu Server 22.04 LTS

   • VM size: Standard_D4s_v5 (4 vCPU, 16GB RAM) or larger. For high integration or commit volume, consult Hivel before finalizing sizing

   • Storage: 50GB Premium SSD managed disk

   • Network Security Group: allow inbound on ports 22, 80, 443, 3000, 4317 (required only while integrating Claude Code), and 5432

2. Note the VM's public and private IP address

Step 2: Install Required Software

On the VM, via SSH:

# Update system
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 Azure CLI (for managing your Azure resources and Key Vault, if used)
curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash

# Install AWS CLI (required, Hivel's container registry and installer package are hosted on AWS)
curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
unzip awscliv2.zip
sudo ./aws/install

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

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

If docker ps still asks for sudo, run newgrp docker or reboot the VM.

Step 3: Configure the AWS CLI

On the VM:

Hivel's Docker images and installer package are hosted on AWS even though your infrastructure runs on Azure.

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 Account, UserId, and Arn fields. If it fails with "Unable to locate credentials," re-run aws configure and check cat ~/.aws/credentials.

Step 4: Provision Azure Database for PostgreSQL

In Azure Portal:

1. Create Azure Database for PostgreSQL > Flexible Server with:

   • Version: PostgreSQL 12 or higher

   • Compute tier: General Purpose, Standard_D2s_v3 or larger

   • Storage: 20GB or more

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

   • Admin password: choose a strong password and save it

2. Configure server parameters: go to Server parameters, set require_secure_transport to OFF (this deployment uses network-level isolation as the security boundary), save. If marked "Static," restart the server

3. Note: server name/host (e.g., myserver.postgres.database.azure.com), port (usually 5432), admin username, admin password

4. Configure networking on the Networking page:

   • Private access (VNet Integration): recommended for production if the VM is in the same virtual network

   • Public access: with a firewall rule restricting access to the VM's public IP (rule name allow-vm, start/end IP = VM's public IP)

Expected: server shows Available status.

Step 5: Create the insightly Database

On the VM (or Azure Portal):

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

# Azure Flexible Server requires SSL by default
psql "host=<your-server>.postgres.database.azure.com port=5432 dbname=postgres user=<admin-username> password=<admin-password> sslmode=require"

CREATE DATABASE insightly;
\q

If you only have console access, use Azure Portal > your PostgreSQL server > Query editor (preview), connect with admin credentials, and run CREATE DATABASE insightly;.

If creation fails: a connection timeout means the firewall rule hasn't been added (recheck Step 4); an SSL-related error means sslmode=require was omitted.

Step 6: Download the Installer and License Files

On the 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

Confirm with ls that deploy.sh, config/, license/, services/, and scripts/ are present. Get your exact S3 bucket path or pre-signed URL from Hivel support. If download fails with "Access Denied," your AWS credentials lack S3 permission; confirm with Hivel which credentials to use or request a pre-signed URL.

Copy license files:

Locate your license files (they may not be in the license/ directory initially), then copy them to /opt/hivel-onprem/license/:

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

# Verify
ls -l license/

Step 7: Test AWS ECR Access

On the VM:

Hivel's Docker images are stored in AWS ECR at 730335373269.dkr.ecr.ap-south-1.amazonaws.com.

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: push Hivel's images to your own AWS 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 8: Configure the Environment File: Phase 1 (Migration Credentials)

On the VM:

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

Set the database variables to your PostgreSQL server's admin credentials:

# Your Azure PostgreSQL server host (from Azure Portal)
DB_HOST=your-server.postgres.database.azure.com

# Port (usually 5432)
DB_PORT=5432

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

# Server admin username (for migration only)
DB_USER=postgres

# Server admin password (for migration only)
DB_PASSWORD='your_admin_password'

If credentials are stored in Azure Key Vault:

az keyvault secret show --vault-name <your-vault-name> --name <secret-name> --query value -o tsv

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 9: Verify Database Connectivity

On the VM:

# Install PostgreSQL client (if not already installed)
sudo apt update && sudo apt install -y postgresql-client

# Test connection (Azure requires SSL by default)
psql "host=$DB_HOST port=$DB_PORT dbname=$DB_NAME user=$DB_USER password=$DB_PASSWORD sslmode=require"

# Or using environment variables
export PGPASSWORD='your_password'
psql -h $DB_HOST -U $DB_USER -d $DB_NAME -p $DB_PORT

Expected result: an insightly=# prompt with no errors. Do not continue until this works.

Step 10: Run the Database Migration

On the VM:

This runs once only, before any other services start. Verify .env currently holds Phase 1 (admin) credentials first; running migration with limited privileges will fail.

cd /opt/hivel-onprem

# Verify .env has admin credentials
cat config/.env | grep DB_USER
cat config/.env | grep DB_PASSWORD

# Run the one-time migration
./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 on an already-initialized database.

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

On the 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 created by flyway-migration. If you customized the password before running migration, use that same password here. All services from this point on connect using this application user, not the server admin account.

Step 12: Deploy All Services

On the VM:

cd /opt/hivel-onprem

# Deploy all VM services
./deploy.sh --vm

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.

Step 13: Set Up Log Rotation

On the VM:

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

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

# Manually test rotation (optional)
sudo ./scripts/docker-log-rotate.sh

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 the 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 VM public IP (testing/pilots only, no load balancing or HTTPS unless you also do Step 15): http://<vm-public-ip>:3000

• Azure Load Balancer (stable, no custom domain or HTTPS yet): create a Standard Load Balancer, configure a backend pool pointing to the VM on ports 80 and 3000, configure health probes and load balancing rules, access via the Load Balancer's public IP or DNS name

• Azure DNS + Load Balancer (recommended for production): create a Load Balancer or Application Gateway, create an Azure DNS zone for your domain, create an A record pointing to it, configure an SSL/TLS certificate (Application Gateway or Key Vault-managed). Access via https://your-domain.com. Alternatively, use Caddy (Step 15) for a lighter-weight HTTPS solution on smaller deployments

Deployment is complete when: all containers are healthy, every endpoint returns healthy, the app is reachable at your configured address, 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 Azure Portal, then on the VM:

Modern browsers restrict crypto.randomUUID, used on the sign-up page, to secure contexts (HTTPS or localhost). This is a lighter-weight alternative to standing up a full Load Balancer or Application Gateway, suitable for smaller deployments and pilots.

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

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

In the VM's Network Security Group: add inbound rules for port 80 (source Any, required for Let's Encrypt's HTTP-01 validation) and port 443 (source Any, or your office/VPN CIDR).

On the 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 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 Azure Setup Guide for detailed instructions.

Back to Azure

Hivel On-Premises Deployment Guide (Azure)