ansible/docs/guides/setup.md

Initial Setup Guide

Complete guide for setting up your Ansible infrastructure management system.

Prerequisites

• Control Machine Requirements:

  • Linux/macOS/WSL
  • Python 3.x installed
  • Git installed
  • SSH client

• Target Machine Requirements:

  • SSH server running
  • Python 3.x installed
  • User with sudo privileges

Step 1: Clone Repository

git clone <your-repo-url>
cd ansible

Step 2: Install Ansible

Ubuntu/Debian

sudo apt update
sudo apt install ansible python3-pip

macOS

brew install ansible

Python pip

pip3 install ansible

Step 3: Install Dependencies

# Install required Ansible collections
make bootstrap

# Or manually:
ansible-galaxy collection install -r collections/requirements.yml

Step 4: Configure Inventory

Edit hosts file to match your infrastructure:

[dev]
dev01 ansible_host=192.168.1.100
bottom ansible_host=192.168.1.101
debianDesktopVM ansible_host=192.168.1.102

[local]
localhost ansible_connection=local

[gitea]
giteaVM ansible_host=192.168.1.110

[portainer]
portainerVM ansible_host=192.168.1.111

Step 5: Set Up SSH Access

Generate SSH Key (if needed)

ssh-keygen -t ed25519 -C "ansible@control"

Copy Key to Hosts

ssh-copy-id user@dev01
ssh-copy-id user@bottom
# Repeat for all hosts

Test Connection

make status
# Or:
ansible all -m ping

Step 6: Configure Vault

Vault stores sensitive data like passwords and API keys.

Create Vault Password

# Option 1: Password file (recommended)
echo "your-secure-password" > ~/.ansible-vault-pass
chmod 600 ~/.ansible-vault-pass

# Option 2: Use interactive prompt (add --ask-vault-pass to commands)

Create Vault File

make create-vault

Add Required Secrets

Add these variables when the editor opens:

---
# Tailscale (if using VPN)
vault_tailscale_auth_key: "tskey-auth-..."

# Proxmox (if creating VMs)
vault_proxmox_host: "192.168.1.10"
vault_proxmox_user: "root@pam"
vault_proxmox_password: "proxmox-password"
vault_vm_cipassword: "vm-default-password"

# SSH Keys
vault_ssh_public_key: "ssh-ed25519 AAAA..."

Step 7: Configure Variables

Global Settings

Edit inventories/production/group_vars/all/main.yml:

# Timezone and locale
timezone: "America/New_York"  # Your timezone
locale: "en_US.UTF-8"

# User configuration
default_user: "your-username"
default_shell: "/usr/bin/zsh"

# Security settings
ssh_port: 22
ssh_permit_root_login: "no"

Host-Specific Settings

Create/edit inventories/production/host_vars/<hostname>.yml for host-specific configuration.

Step 8: Test Configuration

Always test before applying changes:

# Dry run on all hosts
make check

# Dry run on specific host
make check HOST=dev01

# Check specific role
ansible-playbook playbooks/development.yml --check --tags docker

Step 9: Deploy

Full Deployment

# Deploy to all development hosts
make apply

# Deploy to specific host
make dev HOST=dev01

Selective Deployment

# Install only Docker
make docker

# Configure only shell
make shell

# Deploy Tailscale VPN
make tailscale

Step 10: Verify Installation

# Check system status
make status

# Gather facts
make facts

# Check specific services
ansible dev -m shell -a "docker --version"
ansible dev -m shell -a "tailscale status"

Common Issues

SSH Connection Failed

• Verify SSH keys are copied: ssh-copy-id user@host
• Check SSH service: ssh user@host
• Verify inventory file has correct IP/hostname

Vault Password Issues

• Check vault password file exists and has correct permissions
• Verify password is correct: ansible-vault view inventories/production/group_vars/all/vault.yml

Python Not Found

• Install Python on target: sudo apt install python3
• Set Python interpreter in inventory:

  dev01 ansible_host=192.168.1.100 ansible_python_interpreter=/usr/bin/python3
  

Sudo Password Required

• Configure passwordless sudo for automation user
• Or use --ask-become-pass flag

Next Steps

1. Configure Tailscale VPN for secure networking
2. Set up security hardening
3. Deploy monitoring
4. Create custom roles for your specific needs

Getting Help

• Run make help for available commands
• Check role README files in roles/*/README.md
• Review example playbooks in repository
• Check Ansible documentation at https://docs.ansible.com