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

3.1 KiB

Raw Blame History

Ansible Vault Guide

Ansible Vault encrypts sensitive data like passwords and API keys while keeping them usable in playbooks.

Quick Start

Create Vault

make edit-group-vault

Add Secrets

When editor opens, add your secrets:

---
# Authentication Keys
vault_tailscale_auth_key: "tskey-auth-..."
vault_proxmox_password: "super-secret"

# API Keys
vault_github_token: "ghp_..."
vault_docker_hub_token: "dckr_..."

# Passwords
vault_db_password: "complex-password"
vault_vm_cipassword: "vm-user-password"

# SSH Keys
vault_ssh_public_key: "ssh-ed25519 AAAA..."

Use in Playbooks

Reference vault variables with {{ vault_variable_name }}:

tailscale_auth_key: "{{ vault_tailscale_auth_key }}"
database_password: "{{ vault_db_password }}"

File Structure

inventories/production/
├── group_vars/
│   └── all/
│       ├── main.yml       # Plain text configuration
│       └── vault.yml      # Encrypted secrets (edit with make edit-group-vault)
└── host_vars/
    ├── dev01.yml          # Host-specific plain text
    └── dev01/
        └── vault.yml      # Host-specific secrets (edit with make edit-vault HOST=dev01)

Common Commands

# Edit group vault (production inventory)
make edit-group-vault

# Edit host-specific vault
make edit-vault HOST=dev01

# View decrypted contents
ansible-vault view inventories/production/group_vars/all/vault.yml

# Change vault password
ansible-vault rekey inventories/production/group_vars/all/vault.yml

Password Management

Option 1: Password File (Recommended for Automation)

echo "your-vault-password" > ~/.ansible-vault-pass
chmod 600 ~/.ansible-vault-pass

Option 2: Interactive (More Secure)

Add --ask-vault-pass to commands or let Makefile handle it.

Best Practices

What to Encrypt

✅ Put in Vault:

API keys and tokens
Passwords and passphrases
Private keys and certificates
Database credentials
Any sensitive configuration

❌ Keep in Plain Text:

Non-sensitive configuration
Default settings
Public information
Documentation

Naming Convention

Prefix vault variables with vault_ for clarity:

vault_db_password → encrypted in vault
db_host → plain text in all.yml

Security Tips

Never commit unencrypted secrets
Use different vault passwords per environment
Rotate vault passwords periodically
Limit vault file access (chmod 600)
Use git-crypt or similar for additional protection

Troubleshooting

"Attempting to decrypt but no vault secrets found"

Ensure vault password file exists: ~/.ansible-vault-pass
Check file permissions: chmod 600 ~/.ansible-vault-pass

"ERROR! Decryption failed"

Wrong password - verify vault password
Corrupted vault file - recreate from secure storage

Variables not being replaced

Check variable naming matches exactly
Ensure vault file is in correct location
Verify vault file is properly encrypted

Tailscale Setup - Uses vault for auth keys
Security Best Practices - Overall security guidelines

3.1 KiB Raw Blame History