e9fd12d949
NEW FILES: ========== 📄 CUSTOMIZATION_CHECKLIST.md - Complete list of everything that needs customization - Organized by priority: Critical, Important, Optional - Covers .env, Ansible, Gitea secrets, email, etc. - Quick action checklist for deployment 📄 ANSIBLE_HANDOFF.md - Guide for integrating POTE with existing Ansible system - Explains what Ansible needs to know - Variable reference and secrets management - Multi-environment deployment strategy - Example playbook and testing instructions 📄 MOVE_ANSIBLE_TO_SEPARATE_REPO.md - Explains why ansible/ should be in infrastructure repo - Step-by-step migration guide - Final directory structure for both repos - Benefits and workflow after migration KEY INSIGHT: ============ The ansible/ directory doesn't belong in the POTE app repo because: - Ansible runs BEFORE the app exists (creates container, deploys app) - Creates circular dependency (Ansible clones repo that contains Ansible) - Should live in centralized infrastructure repository NEXT STEPS: =========== 1. Review CUSTOMIZATION_CHECKLIST.md for deployment config 2. Copy ansible/ to infrastructure repo 3. Remove ansible/ from POTE repo (keep handoff docs) 4. Deploy via centralized Ansible system
249 lines
7.0 KiB
Markdown
249 lines
7.0 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# From your Ansible repository:
|
|
ansible-playbook playbooks/deploy-pote.yml --limit production
|
|
```
|
|
|
|
### Updating POTE Application
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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.
|
|
|