ansible/docs/guides/app_stack_execution_flow.md

App stack execution flow (what happens when you run it)

This document describes exactly what Ansible runs and what it changes when you execute the Proxmox app stack playbooks.

Entry points

• Recommended end-to-end run:
  • playbooks/app/site.yml
• Repo-root wrappers (equivalent):
  • site.yml (imports playbooks/site.yml, and you can --tags app)
  • provision_vms.yml (imports playbooks/app/provision_vms.yml)
  • configure_app.yml (imports playbooks/app/configure_app.yml)

High-level flow

When you run playbooks/app/site.yml, it imports two playbooks in order:

1. playbooks/app/provision_vms.yml (Proxmox API changes happen here)
2. playbooks/app/configure_app.yml (SSH into guests and configure OS/app)

Variables that drive everything

All per-project/per-env inputs come from:

• inventories/production/group_vars/all/main.yml → app_projects

Each app_projects.<project>.envs.<env> contains:

• name (container hostname / inventory host name)
• vmid (Proxmox CTID)
• ip (static IP in CIDR form, e.g. 10.0.10.101/24)
• gateway (e.g. 10.0.10.1)
• branch (dev, qa, main)
• env_vars (key/value map written to /srv/app/.env.<env>)

Proxmox connection variables are also read from inventories/production/group_vars/all/main.yml but are usually vault-backed:

• proxmox_host: "{{ vault_proxmox_host }}"
• proxmox_user: "{{ vault_proxmox_user }}"
• proxmox_node: "{{ vault_proxmox_node | default('pve') }}"

Phase 1: Provisioning via Proxmox API

File chain

playbooks/app/site.yml imports playbooks/app/provision_vms.yml, which does:

• Validates app_project exists (if you passed one)
• Loops projects → includes playbooks/app/provision_one_guest.yml
• Loops envs inside the project → includes playbooks/app/provision_one_env.yml

Preflight IP safety check

In playbooks/app/provision_one_env.yml:

• It runs ping against the target IP.
• If the IP responds, the play fails to prevent accidental duplicate-IP provisioning.
• You can override the guard (not recommended) with -e allow_ip_conflicts=true.

What it creates/updates in Proxmox

In playbooks/app/provision_one_env.yml it calls role roles/proxmox_vm with LXC variables.

roles/proxmox_vm/tasks/main.yml dispatches:

• If proxmox_guest_type == 'lxc' → includes roles/proxmox_vm/tasks/lxc.yml

roles/proxmox_vm/tasks/lxc.yml performs:

1. Build CT network config

   • Produces a netif dict like:
     • net0: name=eth0,bridge=vmbr0,firewall=1,ip=<CIDR>,gw=<GW>

2. Create/update the container

   • Uses community.proxmox.proxmox with:
     • state: present
     • update: true (so re-runs reconcile config)
     • vmid, hostname, ostemplate, CPU/mem/swap, rootfs sizing, netif
     • pubkey and optionally password for initial root access

3. Start the container

   • Ensures state: started (if lxc_start_after_create: true)

4. Wait for SSH

   • wait_for: host=<ip> port=22

Dynamic inventory creation

Still in playbooks/app/provision_one_env.yml, it calls ansible.builtin.add_host so the guests become available to later plays:

• Adds the guest to groups:
  • app_all
  • app_<project>_all
  • app_<project>_<env>
• Sets:
  • ansible_host to the IP (without CIDR)
  • ansible_user: root (bootstrap user for first config)
  • app_project, app_env facts

Phase 2: Configure OS + app on the guests

playbooks/app/configure_app.yml contains two plays:

Play A: Build dynamic inventory (localhost)

This play exists so you can run configure_app.yml even if you didn’t run provisioning in the same Ansible invocation.

• It loops over projects/envs from app_projects
• Adds hosts to:
  • app_all, app_<project>_all, app_<project>_<env>
• Uses:
  • ansible_user: "{{ app_bootstrap_user | default('root') }}"

Play B: Configure the hosts (SSH + sudo)

Targets:

• If you pass -e app_project=projectA → hosts: app_projectA_all
• Otherwise → hosts: app_all

Tasks executed on each guest:

1. Resolve effective project/env variables

   • project_def = app_projects[app_project]
   • env_def = app_projects[app_project].envs[app_env]

2. Role: base_os (roles/base_os/tasks/main.yml)

   • Updates apt cache
   • Installs baseline packages (git/curl/nodejs/npm/ufw/etc.)
   • Creates appuser (passwordless sudo)
   • Adds your SSH public key to appuser
   • Enables UFW and allows:
     • SSH (22)
     • backend port (default 3001, overridable per project)
     • frontend port (default 3000, overridable per project)

3. Role: app_setup (roles/app_setup/tasks/main.yml)

   • Creates:
     • /srv/app
     • /srv/app/backend
     • /srv/app/frontend
   • Writes the env file:
     • /srv/app/.env.<dev|qa|prod> from template roles/app_setup/templates/env.j2
   • Writes the deploy script:
     • /usr/local/bin/deploy_app.sh from roles/app_setup/templates/deploy_app.sh.j2
     • Script does:
       • git clone if missing
       • git checkout/pull correct branch
       • runs backend install + migrations
       • runs frontend install + build
       • restarts systemd services
   • Writes systemd units:
     • /etc/systemd/system/app-backend.service from app-backend.service.j2
     • /etc/systemd/system/app-frontend.service from app-frontend.service.j2
   • Reloads systemd and enables/starts both services

What changes on first run vs re-run

• Provisioning:
  • First run: creates CTs in Proxmox, sets static IP config, starts them.
  • Re-run: reconciles settings because update: true is used.
• Configuration:
  • Mostly idempotent (directories/templates/users/firewall/services converge).

Common “before you run” checklist

• Confirm app_projects has correct IPs/CTIDs/branches:
  • inventories/production/group_vars/all/main.yml
• Ensure vault has Proxmox + SSH key material:
  • inventories/production/group_vars/all/vault.yml
  • Reference template: inventories/production/group_vars/all/vault.example.yml