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:

```bash
./scripts/utils/prerequisites-check.sh
```

### Step 1.2: Configure Environment

Create and configure `.env` file:

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

### Step 1.3: Test Connections

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

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

```bash
./infrastructure/proxmox/cluster-setup.sh
```

### Step 2.3: Configure Network on Node 2

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

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

### Step 2.5: Verify Cluster

```bash
# On either node
pvecm status
pvecm nodes
```

## Phase 3: Azure Arc Onboarding

### Step 3.1: Prepare Azure

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

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

### Step 3.3: Create Service VMs

Create VMs using Proxmox Web UI or Terraform:

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

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

## Phase 4: Kubernetes Deployment

### Step 4.1: Install K3s

**On K3s VM:**

```bash
./infrastructure/kubernetes/k3s-install.sh
```

### Step 4.2: Verify K3s

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

### Step 4.3: Onboard to Azure Arc

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

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

### Step 4.4: Install Base Infrastructure

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

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

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

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

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

```bash
pvecm status
pvecm nodes
```

### Verify Azure Arc

In Azure Portal:
- Navigate to Azure Arc → Servers
- Verify all hosts and VMs are connected

### Verify Kubernetes

```bash
kubectl get nodes
kubectl get pods --all-namespaces
```

### Verify Services

```bash
kubectl get services --all-namespaces
kubectl get ingress --all-namespaces
```

## Troubleshooting

See [Troubleshooting Guide](../troubleshooting/common-issues.md) 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](../operations/runbooks/)

## Additional Resources

- [Deployment Guide](../deployment/deployment-guide.md)
- [Bring-Up Checklist](../deployment/bring-up-checklist.md)
- [Architecture Overview](../architecture/overview.md)