ansible/README.md

# Ansible Development Environment Setup

This Ansible playbook automates the setup of development environments across multiple machines.

## 🏗️ Architecture

### Host Groups
- `dev`: Development machines (devVM, bottom, debianDesktopVM)
- `gitea`: Gitea server
- `portainer`: Portainer container management
- `homepage`: Homepage dashboard
- `ansible`: Ansible control node

### Roles

#### Core Roles
- **`maintenance`**: System updates, package cleanup, and reboots
- **`base`**: Core system packages, security tools, and system hardening
- **`development`**: Development tools (git, nodejs, build-essential, python3)
- **`shell`**: Shell configuration (zsh + oh-my-zsh + powerlevel10k)
- **`docker`**: Docker CE installation and user configuration
- **`ssh`**: SSH server and firewall configuration
- **`user`**: User management

#### Application Roles
- **`applications`**: Desktop applications (Brave, LibreOffice, Redshift, Evince)
- **`snap`**: Snap daemon and snap applications (VSCode, Cursor)

## 🚀 Usage

### Prerequisites
```bash
# Install required collections
ansible-galaxy collection install -r collections/requirements.yml
```

### Vault Password Setup
Host variables are encrypted with Ansible Vault. You have two options:

#### Option 1: Vault Password File (Recommended)
Create a vault password file:
```bash
# Create the vault password file
echo "your_vault_password" > ~/.ansible-vault-pass
chmod 600 ~/.ansible-vault-pass
```

#### Option 2: Interactive Password Prompt
Use `--ask-vault-pass` with each command to be prompted for the vault password.

### Basic Setup
```bash
# Run on all development machines (with vault password file)
ansible-playbook dev-playbook.yml

# Run on all development machines (interactive vault password)
ansible-playbook dev-playbook.yml --ask-vault-pass

# Run on specific host
ansible-playbook dev-playbook.yml --limit devVM

# Skip reboots for specific host
ansible-playbook dev-playbook.yml --limit bottom
```

### Selective Execution with Tags
```bash
# Security-related roles only
ansible-playbook dev-playbook.yml --tags security

# Development tools only
ansible-playbook dev-playbook.yml --tags development,docker

# Applications only
ansible-playbook dev-playbook.yml --tags apps

# Skip maintenance
ansible-playbook dev-playbook.yml --skip-tags maintenance
```

### Skip Reboots
Add `skip_reboot=true` to host variables:
```ini
[dev]
bottom ansible_host=10.0.10.156 ansible_user=beast skip_reboot=true
```

### Debug Output
Control debug information display with the `ansible_debug_output` variable:

```bash
# Default: No debug output (clean, production-ready output)
ansible-playbook dev-playbook.yml --limit devVM

# Enable debug output (shows detailed status information)
ansible-playbook dev-playbook.yml --limit devVM -e "ansible_debug_output=true"

# Set permanently in group_vars/all.yml
ansible_debug_output: true
```

### Dry Run
```bash
# Check what would be changed
ansible-playbook dev-playbook.yml --check

# Verbose output
ansible-playbook dev-playbook.yml -v
```

## 🔧 Configuration

### Global Variables (`group_vars/all.yml`)
- `timezone`: System timezone (default: UTC)
- `locale`: System locale (default: en_US.UTF-8)
- `ansible_debug_output`: Show debug information (default: false)
- `fail2ban_bantime`: Ban duration in seconds
- `fail2ban_findtime`: Time window for failures
- `fail2ban_maxretry`: Max failures before ban

### Host Variables (`host_vars/`)
- `skip_reboot`: Skip automatic reboots
- Encrypted variables for sensitive data

## 🛡️ Security Features

### Fail2ban Configuration
- SSH brute force protection
- Configurable ban times and retry limits
- Email notifications (configured in template)

### UFW Firewall
- Deny-by-default policy
- SSH access allowed
- Automatic enablement

### System Hardening
- Timezone and locale configuration
- Security package installation
- Monitoring tools (htop, iotop, nethogs, logwatch)

## 📦 Installed Packages

### Base System
- `htop`, `curl`, `wget`, `unzip`, `xclip`
- `net-tools`, `ufw`, `fail2ban`
- `iotop`, `nethogs`, `logwatch`

### Development Tools
- `git`, `nodejs`, `npm`
- `build-essential`, `python3`, `python3-pip`

### Applications
- `brave-browser`, `libreoffice`, `evince`, `redshift`
- `code` (VSCode), `cursor` (via snap)

### Docker
- Docker CE with all components
- Docker Compose
- User added to docker group

## 🔄 Maintenance

### Automatic Updates
The maintenance role handles:
- Package updates (`apt upgrade`)
- Unused package removal (`apt autoremove`)
- Cache cleanup (`apt autoclean`)
- Conditional reboots

### Manual Maintenance
```bash
# Update only maintenance role
ansible-playbook dev-playbook.yml --tags maintenance

# Skip maintenance
ansible-playbook dev-playbook.yml --skip-tags maintenance
```

## 🐛 Troubleshooting

### Common Issues

1. **SSH Connection Issues**
   - Check `ansible.cfg` SSH settings
   - Verify host keys and user permissions

2. **Package Installation Failures**
   - Run with `-v` for verbose output
   - Check internet connectivity on target hosts

3. **Reboot Issues**
   - Use `skip_reboot=true` for problematic hosts
   - Check maintenance role handlers

### Debug Commands
```bash
# Test connectivity
ansible dev -m ping

# Check facts
ansible dev -m setup

# Run specific role
ansible-playbook dev-playbook.yml --tags base
```

## 📝 File Structure
```
ansible/
├── ansible.cfg              # Ansible configuration
├── hosts                    # Inventory file
├── dev-playbook.yml         # Main development playbook
├── group_vars/
│   └── all.yml             # Global variables
├── host_vars/              # Host-specific variables
└── roles/
    ├── maintenance/         # System maintenance
    ├── base/               # Core system setup
    ├── development/        # Development tools
    ├── shell/              # Shell configuration
    ├── docker/             # Docker installation
    ├── ssh/                # SSH configuration
    ├── user/               # User management
    ├── applications/       # Desktop applications
    └── snap/               # Snap applications
```

## 🤝 Contributing

1. Test changes with `--check` first
2. Update documentation for new roles/tasks
3. Use proper handlers for service restarts
4. Follow existing naming conventions