POTE/ANSIBLE_HANDOFF.md

POTE Ansible Integration - Handoff Guide

🎯 Purpose

This document explains what your Ansible auto-configure system needs to know to deploy POTE across different environments.

Note: The Ansible code in ansible/ directory should be moved to your Ansible repository, not kept here in the POTE app repo.

---

📦 What to Move to Your Ansible Repository

Files to Extract from POTE Repo

# Copy these to your Ansible repository:
ansible/
├── README.md                           → roles/pote/README.md
├── roles/pote/defaults/main.yml        → roles/pote/defaults/main.yml
├── group_vars/
│   ├── all.yml                         → group_vars/all.yml (merge with existing)
│   ├── development.yml                 → group_vars/development.yml (merge)
│   ├── staging.yml                     → group_vars/staging.yml (merge)
│   └── production.yml                  → group_vars/production.yml (merge)
├── inventory.example.yml               → inventory.example.yml (reference)
└── vault.example.yml                   → vault.example.yml (reference)

What to Keep in POTE Repo

# Keep these for deployment reference:
docs/08_proxmox_deployment.md           # Manual deployment guide
scripts/proxmox_setup.sh                # Bootstrap script (if needed)
CUSTOMIZATION_CHECKLIST.md             # Configuration reference

---

🔧 Integration with Your Ansible System

1. Create POTE Role in Your Ansible Repo

# In your Ansible repository:
roles/
└── pote/
    ├── defaults/
    │   └── main.yml          # Copy from POTE repo
    ├── tasks/
    │   └── main.yml          # Create based on requirements below
    ├── templates/
    │   └── env.j2            # Create for .env file
    ├── handlers/
    │   └── main.yml          # Restart services, etc.
    └── README.md             # Copy from POTE repo

2. Required Ansible Tasks

Your roles/pote/tasks/main.yml should handle:

Phase 1: System Preparation

• Create application user (poteapp)
• Install system dependencies (Python 3.11, PostgreSQL, build-essential, etc.)
• Configure PostgreSQL database and user

Phase 2: Application Deployment

• Clone POTE repository from Git (using SSH key)
• Create Python virtual environment
• Install Python dependencies
• Create .env file from template
• Run database migrations (alembic upgrade head)

Phase 3: Automation Setup

• Create log directories
• Install cron jobs for daily/weekly reports
• Set up health check monitoring
• Configure email reporting

Phase 4: Security & Cleanup

• Set proper file permissions
• Secure .env file (600)
• Clean up temporary files

---

📋 Variables Your Ansible System Needs

Minimal Required Variables (3)

# Absolute minimum to deploy POTE:
pote_git_repo: "gitea@10.0.30.169:ilia/POTE.git"
pote_git_branch: "main"  # or "dev", "qa" per environment
vault_smtp_password: "{{ vault_smtp_password }}"

Recommended Variables (Environment-Specific)

# Per-environment configuration:
environment: "production"  # or "development", "staging"
pote_git_branch: "main"    # "dev" for development, "qa" for staging

# Database
db_name: "potedb"          # "potedb_dev" for dev, "potedb_qa" for staging
db_user: "poteuser"
db_password: "{{ vault_db_password_prod }}"

# Email
smtp_host: "mail.levkin.ca"
smtp_port: 587
smtp_user: "test@levkin.ca"
from_email: "test@levkin.ca"
smtp_password: "{{ vault_smtp_password }}"
report_recipients: "ilia@levkin.ca"  # Your actual email

# Monitoring
market_tickers: "NVDA,TSLA,AAPL,MSFT,GOOGL,META,AMZN,AMD,INTC,NFLX"
alert_severity: 5

# Automation
pote_enable_cron: true
pote_daily_report_time: "0 6"      # 6:00 AM
pote_weekly_report_time: "0 8"     # 8:00 AM Sunday

Full Variable List

See ansible/roles/pote/defaults/main.yml for all 200+ variables with defaults.

---

🔐 Secrets Management

Required Secrets in Ansible Vault

# In your Ansible vault (group_vars/all/vault.yml):
vault_git_ssh_key: |
  -----BEGIN OPENSSH PRIVATE KEY-----
  your_ssh_private_key_for_gitea
  -----END OPENSSH PRIVATE KEY-----

vault_ssh_public_key: "ssh-rsa AAAAB3NzaC1yc2E..."

vault_smtp_password: "your_email_password"

vault_db_password_dev: "dev_password_123"
vault_db_password_qa: "qa_password_123"
vault_db_password_prod: "strong_production_password"

# Optional:
vault_quiverquant_key: ""
vault_fmp_key: ""

---

🎭 Multi-Environment Strategy

Branch → Environment Mapping

development:
  git_branch: dev
  db_name: potedb_dev
  log_level: DEBUG
  cron_enabled: false  # Manual testing

staging:
  git_branch: qa
  db_name: potedb_qa
  log_level: INFO
  cron_enabled: true

production:
  git_branch: main
  db_name: potedb
  log_level: WARNING
  cron_enabled: true

Deployment Commands

# Deploy to development
ansible-playbook deploy-pote.yml --limit development

# Deploy to staging
ansible-playbook deploy-pote.yml --limit staging

# Deploy to production
ansible-playbook deploy-pote.yml --limit production

---

📝 Example Playbook

---
# deploy-pote.yml
- name: Deploy POTE Application
  hosts: all
  become: yes
  
  pre_tasks:
    - name: Ensure base OS role has run
      debug:
        msg: "Assuming base_os role has already configured the system"
  
  roles:
    - role: pote
      tags: ['pote', 'deploy']

---

🔄 Deployment Workflow

Initial Deployment (New Server)

1. Provision LXC container in Proxmox
2. Run base_os role (your existing role)
3. Run pote role (new role)
4. Verify deployment with health check

Updates (Existing Server)

1. Pull latest code from Git
2. Update dependencies if needed
3. Run migrations (alembic upgrade head)
4. Restart services if needed

Rollback (If Needed)

1. Checkout previous Git tag/commit
2. Run migrations down if needed
3. Restore database backup if needed

---

🧪 Testing the Integration

Dry Run

# Test without making changes
ansible-playbook deploy-pote.yml --limit development --check --diff

Verify Deployment

# SSH into server and run:
cd ~/pote
source venv/bin/activate
python scripts/health_check.py

# Check cron jobs:
crontab -l | grep POTE

# Check logs:
tail -f ~/logs/daily_run.log

---

📊 What POTE Provides for Ansible

1. Configuration Template

The .env file template your Ansible should generate:

# Database
DATABASE_URL=postgresql://{{ db_user }}:{{ db_password }}@localhost:5432/{{ db_name }}

# Email
SMTP_HOST={{ smtp_host }}
SMTP_PORT={{ smtp_port }}
SMTP_USER={{ smtp_user }}
SMTP_PASSWORD={{ smtp_password }}
FROM_EMAIL={{ from_email }}
REPORT_RECIPIENTS={{ report_recipients }}

# Monitoring
MARKET_MONITOR_TICKERS={{ market_tickers }}
ALERT_MIN_SEVERITY={{ alert_severity }}

# Logging
LOG_LEVEL={{ log_level }}
LOG_FILE={{ log_file }}

# Optional API Keys
QUIVERQUANT_API_KEY={{ quiverquant_api_key | default('') }}
FMP_API_KEY={{ fmp_api_key | default('') }}

2. Health Check Endpoint

# Your Ansible can verify deployment with:
python scripts/health_check.py
# Exit code 0 = healthy, non-zero = issues

3. Database Migrations

# Your Ansible should run after code updates:
alembic upgrade head

4. Idempotency

All POTE scripts are idempotent:

• Re-running data fetches won't duplicate records
• Migrations are safe to re-run
• Cron setup checks for existing jobs

---

🚀 Quick Start for Your Ansible Team

1. Copy ansible/ directory from POTE repo to your Ansible repo
2. Customize group_vars/ files with your values
3. Create group_vars/all/vault.yml with secrets
4. Encrypt vault: ansible-vault encrypt group_vars/all/vault.yml
5. Update inventory.yml with your server IPs
6. Test deployment to dev: ansible-playbook deploy-pote.yml --limit development
7. Verify with health check
8. Deploy to staging, then production

---

🔗 Dependencies

System Packages (via apt)

system_packages:
  - python3.11
  - python3.11-venv
  - python3.11-dev
  - python3-pip
  - postgresql
  - postgresql-contrib
  - libpq-dev
  - build-essential
  - git
  - curl
  - htop

Python Packages (via pip)

Installed automatically via pip install -e . from pyproject.toml

---

📞 Support

• POTE Configuration: See CUSTOMIZATION_CHECKLIST.md
• Ansible Variables: See ansible/roles/pote/defaults/main.yml
• Deployment Issues: Check scripts/health_check.py output
• Email Issues: See EMAIL_SETUP.md

---

Last Updated: December 2025 POTE Version: 0.1.0 Target Ansible Version: 2.9+