# 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

```bash
git clone <your-repo-url>
cd ansible
```

## Step 2: Install Ansible

### Ubuntu/Debian
```bash
sudo apt update
sudo apt install ansible python3-pip
```

### macOS
```bash
brew install ansible
```

### Python pip
```bash
pip3 install ansible
```

## Step 3: Install Dependencies

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

```ini
[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)
```bash
ssh-keygen -t ed25519 -C "ansible@control"
```

### Copy Key to Hosts
```bash
ssh-copy-id user@dev01
ssh-copy-id user@bottom
# Repeat for all hosts
```

### Test Connection
```bash
make status
# Or:
ansible all -m ping
```

## Step 6: Configure Vault

Vault stores sensitive data like passwords and API keys.

### Create Vault Password
```bash
# 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
```bash
make create-vault
```

### Add Required Secrets
Add these variables when the editor opens:
```yaml
---
# 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`:
```yaml
# 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:

```bash
# 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
```bash
# Deploy to all development hosts
make apply

# Deploy to specific host
make dev HOST=dev01
```

### Selective Deployment
```bash
# Install only Docker
make docker

# Configure only shell
make shell

# Deploy Tailscale VPN
make tailscale
```

## Step 10: Verify Installation

```bash
# 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:
  ```ini
  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](./tailscale.md) for secure networking
2. [Set up security hardening](./security.md)
3. [Deploy monitoring](./monitoring.md)
4. [Create custom roles](./custom-roles.md) 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