loc_az_hci/docs/getting-started/installation.md

Installation Guide

Step-by-step installation instructions for the Azure Stack HCI infrastructure.

Overview

This guide walks you through the complete installation process, from initial setup to service deployment.

Installation Phases

1. Prerequisites Verification - Verify all requirements are met
2. Proxmox Cluster Setup - Configure Proxmox VE cluster
3. Azure Arc Onboarding - Connect infrastructure to Azure
4. Kubernetes Deployment - Deploy K3s cluster
5. Git Server Setup - Deploy Git repository
6. GitOps Configuration - Configure GitOps workflow
7. Service Deployment - Deploy HC Stack services

Phase 1: Prerequisites Verification

Step 1.1: Verify Prerequisites

Run the prerequisites check:

./scripts/utils/prerequisites-check.sh

Step 1.2: Configure Environment

Create and configure .env file:

cp .env.example .env
# Edit .env with your credentials

Step 1.3: Test Connections

# Test Proxmox connections
./scripts/utils/test-proxmox-connection.sh

# Test Cloudflare (if configured)
./scripts/utils/test-cloudflare-connection.sh

Phase 2: Proxmox Cluster Setup

Step 2.1: Configure Network on Node 1

export NODE_IP=192.168.1.10
export NODE_GATEWAY=192.168.1.1
export NODE_HOSTNAME=pve-node-1

./infrastructure/proxmox/network-config.sh

Step 2.2: Create Cluster on Node 1

./infrastructure/proxmox/cluster-setup.sh

Step 2.3: Configure Network on Node 2

export NODE_IP=192.168.1.11
export NODE_GATEWAY=192.168.1.1
export NODE_HOSTNAME=pve-node-2
export CLUSTER_NODE_IP=192.168.1.10

./infrastructure/proxmox/network-config.sh

Step 2.4: Join Node 2 to Cluster

export NODE_ROLE=join
./infrastructure/proxmox/cluster-setup.sh

Step 2.5: Verify Cluster

# On either node
pvecm status
pvecm nodes

Phase 3: Azure Arc Onboarding

Step 3.1: Prepare Azure

export RESOURCE_GROUP=HC-Stack
export TENANT_ID=$(az account show --query tenantId -o tsv)
export SUBSCRIPTION_ID=$(az account show --query id -o tsv)
export LOCATION=eastus

# Create resource group
az group create --name $RESOURCE_GROUP --location $LOCATION

Step 3.2: Onboard Proxmox Hosts

On each Proxmox node:

./scripts/azure-arc/onboard-proxmox-hosts.sh

Step 3.3: Create Service VMs

Create VMs using Proxmox Web UI or Terraform:

# Using Terraform
cd terraform/proxmox
terraform init
terraform plan
terraform apply

Step 3.4: Onboard VMs to Azure Arc

After VMs are created and OS is installed:

./scripts/azure-arc/onboard-vms.sh

Phase 4: Kubernetes Deployment

Step 4.1: Install K3s

On K3s VM:

./infrastructure/kubernetes/k3s-install.sh

Step 4.2: Verify K3s

export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
kubectl get nodes
kubectl get pods --all-namespaces

Step 4.3: Onboard to Azure Arc

export RESOURCE_GROUP=HC-Stack
export CLUSTER_NAME=proxmox-k3s-cluster

./infrastructure/kubernetes/arc-onboard-k8s.sh

Step 4.4: Install Base Infrastructure

kubectl apply -f gitops/infrastructure/namespace.yaml
kubectl apply -f gitops/infrastructure/ingress-controller.yaml
kubectl apply -f gitops/infrastructure/cert-manager.yaml

Phase 5: Git Server Setup

Option A: Deploy Gitea (Recommended)

export GITEA_DOMAIN=git.local
export GITEA_PORT=3000

./infrastructure/gitops/gitea-deploy.sh

Access Gitea at http://git.local:3000 and complete initial setup.

Option B: Deploy GitLab CE

export GITLAB_DOMAIN=gitlab.local
export GITLAB_PORT=8080

./infrastructure/gitops/gitlab-deploy.sh

Note: GitLab requires at least 8GB RAM.

Phase 6: GitOps Configuration

Step 6.1: Create Git Repository

1. Create a new repository in your Git server (Gitea/GitLab)
2. Clone the repository locally
3. Copy the gitops/ directory to repository

git clone http://git.local:3000/user/gitops-repo.git
cd gitops-repo
cp -r /path/to/loc_az_hci/gitops/* .
git add .
git commit -m "Initial GitOps configuration"
git push

Step 6.2: Connect GitOps to Azure Arc

In Azure Portal:

1. Navigate to: Azure Arc → Kubernetes → Your cluster
2. Go to "GitOps" section
3. Click "Add configuration"
4. Configure:
   • Repository URL: http://git.local:3000/user/gitops-repo.git
   • Branch: main
   • Path: gitops/
   • Authentication: Configure as needed

Phase 7: Service Deployment

Option A: Deploy via GitOps (Recommended)

1. Update Helm chart values in your Git repository
2. Commit and push changes
3. Flux will automatically deploy updates

Option B: Deploy Manually with Helm

# Add Helm charts
helm install besu ./gitops/apps/besu -n blockchain
helm install firefly ./gitops/apps/firefly -n blockchain
helm install chainlink-ccip ./gitops/apps/chainlink-ccip -n blockchain
helm install blockscout ./gitops/apps/blockscout -n blockchain
helm install cacti ./gitops/apps/cacti -n monitoring
helm install nginx-proxy ./gitops/apps/nginx-proxy -n hc-stack

Verification

Verify Proxmox Cluster

pvecm status
pvecm nodes

Verify Azure Arc

In Azure Portal:

• Navigate to Azure Arc → Servers
• Verify all hosts and VMs are connected

Verify Kubernetes

kubectl get nodes
kubectl get pods --all-namespaces

Verify Services

kubectl get services --all-namespaces
kubectl get ingress --all-namespaces

Troubleshooting

See Troubleshooting Guide for common issues and solutions.

Next Steps

After installation:

1. Configure monitoring and alerting
2. Set up backup and disaster recovery
3. Implement security policies
4. Review Operations Guide

Additional Resources

• Deployment Guide
• Bring-Up Checklist
• Architecture Overview