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

2.6 KiB

Raw Blame History

Proxmox App Projects (LXC-first)

This guide documents the modular app-project stack that provisions Proxmox guests (dev/qa/prod) and configures a full-stack app layout on them.

What you get

Proxmox provisioning via API (currently LXC; VM support remains via existing roles/proxmox_vm KVM path)
A deployment user (appuser) with your SSH key
/srv/app/backend and /srv/app/frontend
Env file /srv/app/.env.<dev|qa|prod>
/usr/local/bin/deploy_app.sh to pull the right branch and restart services
systemd services:
- app-backend.service
- app-frontend.service

Where to configure projects

Edit:

inventories/production/group_vars/all/main.yml

Under app_projects, define projects like:

projectA.repo_url
projectA.envs.dev|qa|prod.ip/gateway/branch
projectA.guest_defaults (cores/memory/rootfs sizing)
projectA.deploy.* (install/build/migrate/start commands)

Adding projectB is just adding another top-level app_projects.projectB entry.

Proxmox credentials (vault)

This repo already expects Proxmox connection vars in vault (see existing Proxmox playbooks). Ensure these exist in:

inventories/production/group_vars/all/vault.yml (encrypted)

Common patterns:

vault_proxmox_host: 10.0.10.201
vault_proxmox_user: e.g. root@pam or ansible@pve
vault_proxmox_node: e.g. pve
Either:
- vault_proxmox_password, or
- vault_proxmox_token + vault_proxmox_token_id

Debian LXC template

The LXC provisioning uses lxc_ostemplate, defaulting to a Debian 12 template string like:

local:vztmpl/debian-12-standard_12.7-1_amd64.tar.zst

If your Proxmox has a different template filename, change lxc_ostemplate in inventories/production/group_vars/all/main.yml.

Running it

Provision + configure one project:

ansible-playbook -i inventories/production playbooks/app/site.yml -e app_project=projectA

Provision + configure all projects in app_projects:

ansible-playbook -i inventories/production playbooks/app/site.yml

Only provisioning (Proxmox API):

ansible-playbook -i inventories/production playbooks/app/provision_vms.yml -e app_project=projectA

Only OS/app configuration:

ansible-playbook -i inventories/production playbooks/app/configure_app.yml -e app_project=projectA

Optional: SSH aliases on your workstation

To write ~/.ssh/config entries (disabled by default):

ansible-playbook -i inventories/production playbooks/app/ssh_client_config.yml -e manage_ssh_config=true -e app_project=projectA

This creates aliases like projectA-dev, projectA-qa, projectA-prod.

2.6 KiB Raw Blame History