Skip to content

getting-started.md

Latest commit

 

History

History
156 lines (116 loc) · 3.37 KB

getting-started.md

File metadata and controls

156 lines (116 loc) · 3.37 KB

Getting Started with Proxpilot-AI

This guide will help you set up and deploy Proxpilot-AI in your homelab environment.

Prerequisites

Hardware Requirements

  • Proxmox VE cluster (minimum 3 nodes recommended)
  • 16GB RAM per node (minimum)
  • 100GB storage per node
  • Network connectivity between nodes

Software Requirements

  • Proxmox VE: 7.0 or higher
  • Terraform: 1.5.0 or higher
  • Ansible: 2.14.0 or higher
  • Git: Latest version
  • SSH: Key-based authentication configured

Network Requirements

  • Static IP addresses for all nodes
  • DNS resolution (optional but recommended)
  • Firewall rules for required ports

Installation Steps

Step 1: Clone the Repository

git clone https://github.com/Giuseppe197575/Proxpilot-AI.git
cd Proxpilot-AI

Step 2: Configure Proxmox API Access

  1. Create API token in Proxmox:

    • Log into Proxmox web interface
    • Go to Datacenter → Permissions → API Tokens
    • Create token with appropriate permissions

  2. Update Terraform variables:

    cp terraform/terraform.tfvars.example terraform/terraform.tfvars
nano terraform/terraform.tfvars

    Set the following variables:

    proxmox_api_url = "https://your-proxmox-host:8006/api2/json"
proxmox_api_token_id = "user@pam!token-name"
proxmox_api_token_secret = "your-token-secret"
ssh_public_key = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI..."

Step 3: Configure Inventory

cp inventory/hosts.example.yml inventory/hosts.yml
nano inventory/hosts.yml

Update with your infrastructure details:

  • Proxmox node IPs and hostnames
  • K3s node IPs
  • Service node IPs

Step 4: Initialize the Project

make init

This will:

  • Set up configuration files
  • Check prerequisites
  • Prepare the environment

Step 5: Plan the Deployment

make plan

Review the Terraform plan to ensure it matches your expectations.

Step 6: Deploy Infrastructure

make apply

This will:

  1. Create VMs/LXCs on Proxmox
  2. Configure network settings
  3. Set up base operating systems

Step 7: Deploy Configuration

make config

This will:

  1. Install required packages
  2. Configure services
  3. Deploy K3s cluster
  4. Set up monitoring stack

Verification

After deployment, verify everything is working:

# Test connectivity
./scripts/test-connectivity.sh

# Check K3s cluster
kubectl get nodes
kubectl get pods -A

# Access monitoring
# Grafana: http://<monitoring-ip>:3000
# Prometheus: http://<monitoring-ip>:9090

Common Issues

SSH Connection Issues

  • Ensure SSH keys are properly configured
  • Check firewall rules
  • Verify network connectivity

Proxmox API Errors

  • Verify API token permissions
  • Check Proxmox URL and port
  • Ensure TLS certificates are trusted

Terraform Errors

  • Check Terraform version compatibility
  • Verify variable definitions
  • Review Terraform state files

Next Steps

  1. Customize configurations: Modify Ansible roles and Terraform modules
  2. Add services: Deploy additional applications to K3s
  3. Configure monitoring: Create custom Grafana dashboards
  4. Set up backups: Implement backup strategies
  5. Enable security: Configure firewall and access controls

Getting Help