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

```bash
# 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

```bash
# 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

```bash
# 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)

```yaml
# 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)

```yaml
# 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

```yaml
# 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

```yaml
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

```bash
# 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

```yaml
---
# 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

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

### Verify Deployment

```bash
# 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:

```bash
# 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

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

### 3. Database Migrations

```bash
# 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)

```yaml
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+