# Getting Started

This guide walks through setting up Arvandor from scratch.

## Prerequisites

### Proxmox Host

- Proxmox VE 7.x or 8.x
- Two network bridges:
  - `vmbr0` - Public interface
  - `vmbr1` - Internal VM network (192.168.100.0/24)
- IP forwarding enabled

### VM Template

Create an Arch Linux template (VMID 9000):

1. Download Arch Linux ISO
2. Create VM, install Arch with basic setup
3. Install `openssh`, `python` (for Ansible)
4. Enable cloud-init or configure static user
5. Convert to template

### Local Tools

```bash
# Terraform
wget -O- https://apt.releases.hashicorp.com/gpg | gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/hashicorp.list
sudo apt update && sudo apt install terraform

# Ansible
pip install ansible

# Nebula
wget https://github.com/slackhq/nebula/releases/download/v1.9.0/nebula-linux-amd64.tar.gz
tar xzf nebula-linux-amd64.tar.gz
sudo mv nebula nebula-cert /usr/local/bin/
```

## Step 1: Configure Terraform

```bash
cd terraform

# Copy example configuration
cp terraform.tfvars.example terraform.tfvars

# Edit with your values
vim terraform.tfvars
```

Required variables:
- `proxmox_endpoint` - Your Proxmox API URL
- `proxmox_api_token_id` - API token ID
- `proxmox_api_token_secret` - API token secret
- `proxmox_node` - Node name (e.g., "pve")
- `username` - Default VM username
- `password` - Default VM password
- `ssh_key_path` - Path to your SSH public key

## Step 2: Create Proxmox API Token

In Proxmox:

1. Datacenter → Permissions → API Tokens
2. Add token for a user with `PVEAdmin` or `Administrator` role
3. Copy the token ID and secret

## Step 3: Generate Nebula CA

```bash
cd nebula

# Generate Certificate Authority
nebula-cert ca -name "Arvandor CA" -duration 87600h

# This creates:
# - ca.crt (share with all hosts)
# - ca.key (keep secure!)
```

## Step 4: Provision VMs

```bash
cd terraform

terraform init
terraform plan
terraform apply
```

This creates all VMs defined in the .tf files.

## Step 5: Generate Nebula Certificates

For each VM, generate a certificate:

```bash
cd nebula

# DNS server
nebula-cert sign -ca-crt ca.crt -ca-key ca.key \
  -name "dns" -networks "10.10.10.11/24" -groups "infrastructure" \
  -out-crt configs/1001/dns/dns.crt \
  -out-key configs/1001/dns/dns.key

# Repeat for all VMs...
```

## Step 6: Configure Ansible Inventory

```bash
cd ansible

cp inventory.ini.example inventory.ini
vim inventory.ini
```

Update:
- VM hostnames and IPs
- SSH jump host configuration
- Infrastructure variables

## Step 7: Bootstrap VMs

Run playbooks in order:

```bash
# Update packages, reboot if kernel changed
ansible-playbook -i inventory.ini playbooks/bootstrap.yml

# Configure iptables and fail2ban
ansible-playbook -i inventory.ini playbooks/security.yml

# Join Nebula overlay network
ansible-playbook -i inventory.ini playbooks/nebula.yml
```

## Step 8: Deploy Core Services

```bash
# DNS (required for hostname resolution)
ansible-playbook -i inventory.ini playbooks/dns.yml
ansible-playbook -i inventory.ini playbooks/dns-client.yml

# PostgreSQL HA cluster
ansible-playbook -i inventory.ini playbooks/postgres-ha.yml

# Valkey with Sentinel
ansible-playbook -i inventory.ini playbooks/valkey-sentinel.yml

# Garage S3 storage
ansible-playbook -i inventory.ini playbooks/garage.yml
```

## Step 9: Configure Host Port Forwarding

On the Proxmox host:

```bash
# Copy and configure the script
cp network/port-forward.sh.example /root/network/port-forward.sh
chmod +x /root/network/port-forward.sh
vim /root/network/port-forward.sh

# Test
./port-forward.sh --dry-run

# Apply
./port-forward.sh
```

## Verification

Test connectivity:

```bash
# SSH to VM via Nebula
ssh admin@10.10.10.11

# Test DNS resolution
dig @10.10.10.11 vault-01.nebula

# Test PostgreSQL
psql -h 10.10.10.30 -U postgres -c "SELECT 1"

# Test Valkey
valkey-cli -h 10.10.10.33 PING
```

## Next Steps

- Add your application VMs to `terraform/workloads.tf`
- Create services in `ansible/services.yml`
- Provision app credentials with `data-service.yml`