POTE/MOVE_ANSIBLE_TO_SEPARATE_REPO.md

Move Ansible Code to Separate Repository

❌ Problem

The ansible/ directory in this repository doesn't make sense here because:

1. Ansible runs BEFORE the app exists - it creates the container and deploys the app
2. Ansible belongs in your infrastructure repo - not in the application repo
3. Chicken-and-egg problem - Ansible needs to clone this repo, but the Ansible code is inside it

✅ Solution

Move the Ansible code to your Ansible/infrastructure repository where your other roles live.

---

🚚 Migration Steps

Step 1: Copy Ansible Code to Your Ansible Repo

# From your Ansible repository:
cd /path/to/your/ansible-repo

# Copy the POTE role
cp -r /path/to/pote/ansible/roles/pote roles/

# Merge group_vars (don't overwrite existing files!)
# Manually merge these into your existing group_vars:
# - ansible/group_vars/all.yml
# - ansible/group_vars/development.yml
# - ansible/group_vars/staging.yml
# - ansible/group_vars/production.yml

# Copy examples for reference
cp /path/to/pote/ansible/inventory.example.yml examples/pote-inventory.example.yml
cp /path/to/pote/ansible/vault.example.yml examples/pote-vault.example.yml

Step 2: Remove Ansible Code from POTE Repo

# From the POTE repository:
cd /path/to/pote

# Remove the ansible directory
git rm -r ansible/

# Remove Ansible-specific docs (keep handoff guide)
git rm ANSIBLE_INTEGRATION.md

# Keep these files:
# - ANSIBLE_HANDOFF.md (reference for Ansible team)
# - CUSTOMIZATION_CHECKLIST.md (configuration reference)
# - docs/08_proxmox_deployment.md (manual deployment guide)

# Commit the changes
git add -A
git commit -m "Move Ansible code to infrastructure repository

The ansible/ directory has been moved to the Ansible infrastructure
repository where it belongs. This repo now only contains:
- Application code
- Deployment documentation (ANSIBLE_HANDOFF.md)
- Configuration reference (CUSTOMIZATION_CHECKLIST.md)
- Manual deployment guide (docs/08_proxmox_deployment.md)

Ansible code now lives in: [your-ansible-repo]/roles/pote/"

Step 3: Update Your Ansible Repo

# In your Ansible repository:

# Create the playbook
cat > playbooks/deploy-pote.yml << 'EOF'
---
- name: Deploy POTE Application
  hosts: pote_servers
  become: yes
  
  roles:
    - role: pote
      tags: ['pote', 'deploy']
EOF

# Update inventory (add POTE servers)
# Edit inventory/production.yml, inventory/staging.yml, etc.

# Create/update vault with POTE secrets
ansible-vault edit group_vars/all/vault.yml
# Add: vault_smtp_password, vault_git_ssh_key, vault_db_password_*, etc.

# Test deployment
ansible-playbook playbooks/deploy-pote.yml --limit development --check

---

📁 Final Directory Structure

POTE Application Repo (this repo)

pote/
├── src/pote/                      # Application code
├── tests/                         # Tests
├── scripts/                       # Deployment scripts
├── docs/                          # Documentation
├── .github/workflows/             # CI/CD pipelines
├── ANSIBLE_HANDOFF.md            # ✅ Keep - Reference for Ansible team
├── CUSTOMIZATION_CHECKLIST.md    # ✅ Keep - Configuration guide
├── MOVE_ANSIBLE_TO_SEPARATE_REPO.md  # ✅ Keep - This file
└── pyproject.toml                # Python dependencies

Your Ansible Infrastructure Repo

ansible-infrastructure/
├── roles/
│   ├── base_os/                  # Your existing role
│   ├── pote/                     # ✅ NEW - Moved from POTE repo
│   │   ├── defaults/main.yml
│   │   ├── tasks/main.yml
│   │   ├── templates/env.j2
│   │   └── handlers/main.yml
│   └── ...other roles...
├── playbooks/
│   ├── deploy-pote.yml           # ✅ NEW - POTE deployment playbook
│   └── ...other playbooks...
├── group_vars/
│   ├── all.yml                   # Merged POTE variables
│   ├── all/vault.yml             # Added POTE secrets
│   ├── development.yml           # Merged POTE dev config
│   ├── staging.yml               # Merged POTE staging config
│   └── production.yml            # Merged POTE prod config
├── inventory/
│   ├── production.yml            # Added POTE servers
│   ├── staging.yml               # Added POTE servers
│   └── development.yml           # Added POTE servers
└── examples/
    ├── pote-inventory.example.yml
    └── pote-vault.example.yml

---

🎯 Benefits of This Approach

1. Cleaner Separation - Application code separate from infrastructure code
2. No Circular Dependency - Ansible can clone the app repo without needing to be inside it
3. Centralized Infrastructure - All your Ansible roles in one place
4. Easier Management - Update infrastructure without touching app code
5. Standard Practice - Follows industry best practices

---

🔄 Workflow After Migration

Deploying POTE

# From your Ansible repository:
ansible-playbook playbooks/deploy-pote.yml --limit production

Updating POTE Application

# Option 1: Via Ansible (recommended)
ansible-playbook playbooks/deploy-pote.yml --limit production --tags update

# Option 2: Via Gitea Actions (CI/CD)
# Push to main branch → Gitea Actions runs tests → Auto-deploy

# Option 3: Manual (SSH to server)
cd ~/pote
git pull origin main
source venv/bin/activate
pip install -e .
alembic upgrade head

---

📝 What to Tell Your Ansible Team

Send them:

1. ANSIBLE_HANDOFF.md - Complete integration guide
2. CUSTOMIZATION_CHECKLIST.md - What needs to be configured
3. ansible/ directory - The actual role code

They need to:

1. Copy the role to their Ansible repo
2. Merge the group_vars into their existing structure
3. Add POTE servers to their inventory
4. Add POTE secrets to their vault
5. Test deployment to dev environment
6. Deploy to staging, then production

---

⚠️ Important Notes

Don't Delete These from POTE Repo

Keep these files for reference:

• ANSIBLE_HANDOFF.md - Ansible integration guide
• CUSTOMIZATION_CHECKLIST.md - Configuration reference
• docs/08_proxmox_deployment.md - Manual deployment guide
• scripts/proxmox_setup.sh - Bootstrap script (if needed)

Do Delete These from POTE Repo

Remove these (they belong in Ansible repo):

• ansible/ directory (entire thing)
• ANSIBLE_INTEGRATION.md (redundant with ANSIBLE_HANDOFF.md)

---

🚀 Ready to Move?

Run these commands when ready:

# 1. Backup first (just in case)
cp -r ansible /tmp/pote-ansible-backup

# 2. Remove from POTE repo
git rm -r ansible/
git rm ANSIBLE_INTEGRATION.md
git add -A
git commit -m "Move Ansible code to infrastructure repository"
git push origin dev

# 3. Copy to your Ansible repo (do this manually)
# See "Step 1: Copy Ansible Code to Your Ansible Repo" above

# 4. Test deployment from Ansible repo
# See "Step 3: Update Your Ansible Repo" above

---

Questions? See ANSIBLE_HANDOFF.md for complete integration details.