ilia/ansible
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
ansible/docs/reference/makefile.md
ilia 69a39e5e5b Add POTE app project support and improve IP conflict detection (#3) 
## Summary

This PR adds comprehensive support for deploying the **POTE** application project via Ansible, along with improvements to IP conflict detection and a new app stack provisioning system for Proxmox-managed LXC containers.

## Key Features

### 🆕 New Roles
- **`roles/pote`**: Python/venv deployment role for POTE (PostgreSQL, cron jobs, Alembic migrations)
- **`roles/app_setup`**: Generic app deployment role (Node.js/systemd)
- **`roles/base_os`**: Base OS hardening role

### 🛡️ Safety Improvements
- IP uniqueness validation within projects
- Proxmox-side IP conflict detection
- Enhanced error messages for IP conflicts

### 📦 New Playbooks
- `playbooks/app/site.yml`: End-to-end app stack deployment
- `playbooks/app/provision_vms.yml`: Proxmox guest provisioning
- `playbooks/app/configure_app.yml`: OS + application configuration

## Security
- ✅ All secrets stored in encrypted vault.yml
- ✅ Deploy keys excluded via .gitignore
- ✅ No plaintext secrets committed

## Testing
- ✅ POTE successfully deployed to dev/qa/prod environments
- ✅ All components validated (Git, PostgreSQL, cron, migrations)

Co-authored-by: ilia <ilia@levkin.ca>
Reviewed-on: #3
2026-01-01 11:19:54 -05:00

6.1 KiB
Raw Blame History

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

# 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

make bootstrap
make create-vault
make test
make check
make apply

Adding New Host

make copy-ssh-key HOST=newhost
make edit-vault HOST=newhost
make dev HOST=newhost

System Maintenance

make maintenance-check
make maintenance GROUP=dev
make maintenance-all

Feature Deployment

# Deploy specific features
make docker
make tailscale
make monitoring

Troubleshooting

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