ansible/README.md

# Ansible Infrastructure Management

Comprehensive infrastructure automation for development environments, server management, and VM provisioning.

## 📊 **Current Status**

### ✅ **Completed Infrastructure**
- **Core System**: Base packages, SSH hardening, user management
- **Development Environment**: Git, Node.js, Python, Docker, modern CLI tools  
- **Shell Configuration**: Zsh + Oh My Zsh + Powerlevel10k + plugins
- **Applications**: VS Code, Cursor, Brave, LibreOffice, desktop tools
- **Monitoring**: System monitoring tools + custom scripts (`sysinfo`, `netinfo`)
- **VPN Mesh**: Tailscale integration with automated auth keys
- **Security**: UFW firewall, fail2ban, SSH hardening
- **Maintenance**: Automated package updates and system cleanup

### 🎯 **Next Priorities**
1. **Enhanced monitoring**: Grafana + Prometheus dashboard
2. **Security hardening**: ClamAV antivirus, Lynis auditing, vulnerability scanning
3. **Centralized logging**: ELK stack for log aggregation
4. **CI/CD pipeline**: GitLab Runner or Jenkins integration
5. **Advanced security**: Intrusion detection, automated patching

## 🚀 Quick Start

```bash
# Install dependencies
make bootstrap

# Set up secrets management
make create-vault

# Test configuration (comprehensive)
make test

# Deploy to all hosts (dry run first)
make check
make apply
```

## 📚 Documentation

### Getting Started
- [**Initial Setup Guide**](docs/guides/setup.md) - First-time setup instructions
- [**Ansible Vault Guide**](docs/guides/vault.md) - Managing secrets securely
- [**Tailscale VPN Setup**](docs/guides/tailscale.md) - Mesh networking configuration

### Reference
- [**Installed Applications**](docs/reference/applications.md) - Complete software inventory
- [**Makefile Commands**](docs/reference/makefile.md) - All available make targets
- [**Architecture Overview**](docs/reference/architecture.md) - System design and structure

## 🏗️ Project Structure

```
ansible/
├── Makefile                    # Task automation
├── ansible.cfg                 # Ansible configuration
├── hosts                       # Inventory file
├── collections/               
│   └── requirements.yml       # Galaxy dependencies
├── group_vars/                # Global variables
│   ├── all.yml               
│   └── all/vault.yml          # Encrypted secrets
├── host_vars/                 # Host-specific configs
├── roles/                     # Ansible roles
│   ├── base/                 # Core system setup
│   ├── development/          # Dev tools
│   ├── docker/               # Container platform
│   ├── monitoring/           # System monitoring
│   ├── tailscale/            # VPN networking
│   └── ...                   # Additional roles
├── playbooks/
│   ├── dev-playbook.yml      # Development setup
│   ├── local-playbook.yml    # Local machine
│   ├── maintenance-playbook.yml
│   └── tailscale-playbook.yml
└── docs/                      # Documentation
    ├── guides/               # How-to guides
    └── reference/            # Technical reference
```

## 🎯 Key Features

### Infrastructure Management
- **Automated Provisioning**: Proxmox VM creation and configuration
- **Configuration Management**: Consistent setup across all machines
- **Network Security**: Tailscale VPN mesh networking
- **System Maintenance**: Automated updates and cleanup

### Development Environment
- **Shell Environment**: Zsh + Oh My Zsh + Powerlevel10k
- **Container Platform**: Docker CE with Compose
- **Development Tools**: Node.js, Python, Git, build tools
- **Code Editors**: VS Code, Cursor IDE

### Security & Monitoring
- **SSH Hardening**: Modern crypto, key-only auth, fail2ban
- **Firewall**: UFW with sensible defaults
- **Monitoring Tools**: btop, iotop, nethogs, custom dashboards

## 🧪 Testing & Validation

### Comprehensive Testing
```bash
make test                    # Full test suite (lint + syntax + validation)
make test-syntax            # Syntax and configuration validation only
make lint                   # Ansible-lint only
```

### Testing Coverage
- **Playbook syntax**: All main playbooks and infrastructure playbooks
- **Role validation**: All role test playbooks  
- **Configuration files**: YAML and INI file validation
- **Documentation**: Markdown syntax and link checking (installed via `make bootstrap`)
- **Linting**: Full Ansible best practices validation

## 🖥️ Managed Hosts

| Host | Type | OS | Purpose |
|------|------|-----|---------|
| dev01 | Physical | Debian | Primary development |
| bottom | Physical | Debian | Secondary development |
| debianDesktopVM | VM | Debian | Desktop environment |
| giteaVM | VM | Alpine | Git repository hosting |
| portainerVM | VM | Alpine | Container management |
| homepageVM | VM | Debian | Service dashboard |

## 🔧 Common Tasks

```bash
# System Maintenance
make maintenance              # Update all systems
make maintenance HOST=dev01   # Update specific host

# Development Setup
make docker                   # Install Docker
make shell                    # Configure shell
make apps                     # Install applications

# Network & Security
make tailscale               # Deploy VPN
make security                # Security hardening
make monitoring              # Deploy monitoring

# Infrastructure
make create-vm               # Create new VM
make status                  # Check connectivity
make facts                   # Gather system info
```

## 🛠️ Requirements

### Control Machine (where you run Ansible)
- Python 3.x with `pipx` (recommended) or `pip3`
- Node.js and `npm` (for documentation testing)
- SSH access to target hosts
- Ansible Vault password (for secrets)

### Target Hosts
- SSH server running
- Python 3.x
- `sudo` access for the Ansible user

### Dependency Management
All project dependencies are managed through standard requirements files:
- **`requirements.txt`** - Python packages (ansible, ansible-lint, etc.)
- **`package.json`** - Node.js packages (markdown tools)
- **`collections/requirements.yml`** - Ansible collections

**Setup**: Run `make bootstrap` to install all dependencies automatically.

## 📝 Contributing

1. Test changes with `make check` (dry run)
2. Follow existing patterns and naming conventions
3. Update documentation for new features
4. Encrypt sensitive data with Ansible Vault