arvandor/docs/getting-started.md

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

# 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

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

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

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:

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

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:

# 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

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

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

# 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