ilia/ansible
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
ansible/docs/guides/app_stack_proxmox.md
ilia eef01d87d0 Add POTE app project support and improve IP conflict detection 
- Add roles/pote: Python/venv deployment role with PostgreSQL, cron jobs
- Add playbooks/app/: Proxmox app stack provisioning and configuration
- Add roles/app_setup: Generic app deployment role (Node.js/systemd)
- Add roles/base_os: Base OS hardening role
- Enhance roles/proxmox_vm: Split LXC/KVM tasks, improve error handling
- Add IP uniqueness validation: Preflight check for duplicate IPs within projects
- Add Proxmox-side IP conflict detection: Check existing LXC net0 configs
- Update inventories/production/group_vars/all/main.yml: Add pote project config
- Add vault.example.yml: Template for POTE secrets (git key, DB, SMTP)
- Update .gitignore: Exclude deploy keys, backup files, and other secrets
- Update documentation: README, role docs, execution flow guides

Security:
- All secrets stored in encrypted vault.yml (never committed in plaintext)
- Deploy keys excluded via .gitignore
- IP conflict guardrails prevent accidental duplicate IP assignments
2026-01-01 11:11:17 -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.