# Makefile Commands Reference

Complete reference for all available `make` commands in the Ansible project.

## Core Commands

### Setup & Testing
| Command | Description | Usage |
|---------|-------------|-------|
| `help` | Show all available commands | `make help` |
| `bootstrap` | Install required collections and dependencies | `make bootstrap` |
| `test` | Run all tests (lint + syntax check) | `make test` |
| `test-syntax` | Run syntax check only | `make test-syntax` |
| `lint` | Run ansible-lint on playbooks and roles | `make lint` |
| `check` | Dry-run the development playbook | `make check` |
| `check-local` | Dry-run the local playbook | `make check-local` |

### Deployment
| Command | Description | Usage |
|---------|-------------|-------|
| `apply` | Run development playbook on all dev hosts | `make apply` |
| `local` | Run local playbook on localhost | `make local` |
| `dev` | Run on specific host | `make dev HOST=dev01` |
| `quick` | Quick test and check before applying | `make quick` |

## Feature-Specific Commands

### System Maintenance
| Command | Description | Usage |
|---------|-------------|-------|
| `maintenance` | Run system maintenance | `make maintenance [GROUP=dev] [HOST=dev01]` |
| | | Options: `SERIAL=1 CHECK=true VERBOSE=true` |
| `maintenance-dev` | Run maintenance on dev group | `make maintenance-dev` |
| `maintenance-all` | Run maintenance on all hosts | `make maintenance-all` |
| `maintenance-check` | Dry-run maintenance | `make maintenance-check [GROUP=dev]` |
| `maintenance-verbose` | Maintenance with verbose output | `make maintenance-verbose [GROUP=dev]` |

### Security & Networking
| Command | Description | Usage |
|---------|-------------|-------|
| `security` | Run only security-related roles | `make security` |
| `tailscale` | Install Tailscale on all machines | `make tailscale` |
| `tailscale-check` | Check Tailscale installation (dry-run) | `make tailscale-check` |
| `tailscale-dev` | Install Tailscale on dev machines only | `make tailscale-dev` |
| `tailscale-status` | Check Tailscale status on all machines | `make tailscale-status` |

### Applications & Tools
| Command | Description | Usage |
|---------|-------------|-------|
| `docker` | Install/configure Docker only | `make docker` |
| `shell` | Configure shell only | `make shell` |
| `apps` | Install applications only | `make apps` |
| `monitoring` | Install monitoring tools | `make monitoring` |

## Infrastructure Management

### VM & Host Management
| Command | Description | Usage |
|---------|-------------|-------|
| `create-vm` | Create Ansible controller VM on Proxmox | `make create-vm` |
| `proxmox-info` | Show Proxmox guest info (LXC/VM) | `make proxmox-info [PROJECT=projectA] [ALL=true] [TYPE=lxc\|qemu\|all]` |
| `app-provision` | Provision app project guests on Proxmox | `make app-provision PROJECT=projectA` |
| `app-configure` | Configure OS + app on project guests | `make app-configure PROJECT=projectA` |
| `app` | Provision + configure app project guests | `make app PROJECT=projectA` |
| `ping` | Ping hosts with colored output | `make ping [GROUP=dev] [HOST=dev01]` |
| `facts` | Gather facts from all hosts | `make facts` |
| `test-connectivity` | Test network and SSH access | `make test-connectivity` |
| `show-current` | Show current host (auto-excluded) | `make show-current` |

### SSH & Vault Management
| Command | Description | Usage |
|---------|-------------|-------|
| `copy-ssh-key` | Copy SSH key to specific host | `make copy-ssh-key HOST=giteaVM` |
| `create-vault` | Create encrypted vault file | `make create-vault` |
| `edit-vault` | Edit encrypted host vars | `make edit-vault HOST=dev01` |
| `edit-group-vault` | Edit encrypted group vars (production inventory) | `make edit-group-vault` |

## Utility Commands

### Debugging & Cleanup
| Command | Description | Usage |
|---------|-------------|-------|
| `debug` | Run with debug output enabled | `make debug` |
| `verbose` | Run with verbose output | `make verbose` |
| `clean` | Clean up ansible artifacts | `make clean` |

## Command Options

### Common Variables
Many commands accept these optional variables:

| Variable | Description | Example |
|----------|-------------|---------|
| `HOST` | Target specific host | `HOST=dev01` |
| `GROUP` | Target specific group | `GROUP=dev` |
| `CHECK` | Run in check mode (dry-run) | `CHECK=true` |
| `VERBOSE` | Enable verbose output | `VERBOSE=true` |
| `SERIAL` | Run on hosts one at a time | `SERIAL=1` |

### Examples

```bash
# Deploy to specific host
make dev HOST=bottom

# Maintenance with options
make maintenance GROUP=dev SERIAL=1 CHECK=true

# Test connectivity to specific group
make ping GROUP=gitea

# Edit vault for specific host
make edit-vault HOST=portainerVM

# Dry-run on production
make check GROUP=prod
```

## Workflow Examples

### Initial Setup
```bash
make bootstrap
make create-vault
make test
make check
make apply
```

### Adding New Host
```bash
make copy-ssh-key HOST=newhost
make edit-vault HOST=newhost
make dev HOST=newhost
```

### System Maintenance
```bash
make maintenance-check
make maintenance GROUP=dev
make maintenance-all
```

### Feature Deployment
```bash
# Deploy specific features
make docker
make tailscale
make monitoring
```

### Troubleshooting
```bash
make test-connectivity
make facts
make ping GROUP=dev
make debug
```

## Tips & Best Practices

1. **Always test first**: Use `check` commands before applying changes
2. **Use groups**: Target specific groups instead of all hosts
3. **Verbose for debugging**: Add `VERBOSE=true` when troubleshooting
4. **Serial for safety**: Use `SERIAL=1` for critical changes
5. **Check mode**: Use `CHECK=true` to preview changes

## Environment Variables

The Makefile respects these environment variables:

| Variable | Description | Default |
|----------|-------------|---------|
| `ANSIBLE_CONFIG` | Ansible configuration file | `./ansible.cfg` |
| `ANSIBLE_VAULT_PASSWORD_FILE` | Vault password file | `~/.ansible-vault-pass` |
| `ANSIBLE_HOST_KEY_CHECKING` | SSH host key checking | `False` |

## Getting Help

- Run `make help` to see all available commands
- Commands with `##` comments appear in help output
- Check individual role documentation in `roles/*/README.md`
- Review playbook files for available tags