POTE/ANSIBLE_INTEGRATION.md

# 🤖 Ansible Integration for POTE

## Quick Reference: What Ansible Needs to Know

### 📋 Complete Variable List

```yaml
# =============================================================================
# ESSENTIAL VARIABLES (Must Configure)
# =============================================================================

# Git Repository
pote_git_repo: "gitea@10.0.30.169:ilia/POTE.git"
pote_git_branch: "main"  # or "qa", "dev"
pote_git_ssh_key: "{{ vault_git_ssh_key }}"

# Application User
pote_user: "poteapp"
pote_app_dir: "/home/poteapp/pote"

# Database
pote_db_host: "localhost"
pote_db_name: "potedb"
pote_db_user: "poteuser"
pote_db_password: "{{ vault_db_password }}"

# Email/SMTP
pote_smtp_host: "mail.levkin.ca"
pote_smtp_port: 587
pote_smtp_user: "test@levkin.ca"
pote_smtp_password: "{{ vault_smtp_password }}"
pote_from_email: "test@levkin.ca"
pote_report_recipients: "test@levkin.ca"

# =============================================================================
# SYSTEM PACKAGES (What to Install)
# =============================================================================

# Python packages
pote_python_packages:
  - python3
  - python3-pip
  - python3-venv
  - python3-dev
  - build-essential

# System dependencies
pote_system_packages:
  - git
  - curl
  - ca-certificates
  - postgresql-client
  - libpq-dev
  - gcc
  - make

# =============================================================================
# PORTS & FIREWALL
# =============================================================================

# POTE doesn't expose HTTP ports (CLI/cron only)
# But allow SSH for deployment
pote_allow_ssh_port: 22

# Future FastAPI backend (optional)
pote_backend_port: 8000
pote_enable_backend: false  # Not implemented yet

# =============================================================================
# AUTOMATION / CRON
# =============================================================================

pote_enable_cron: true
pote_daily_report_time: "0 6"  # 6:00 AM
pote_weekly_report_time: "0 8 0"  # Sunday 8:00 AM
pote_health_check_time: "0 */6"  # Every 6 hours

# =============================================================================
# ENVIRONMENT-SPECIFIC
# =============================================================================

# Development
environment: "development"
git_branch: "dev"
db_name: "potedb_dev"
log_level: "DEBUG"

# Staging/QA
environment: "staging"
git_branch: "qa"
db_name: "potedb_qa"
log_level: "INFO"

# Production
environment: "production"
git_branch: "main"
db_name: "potedb"
log_level: "INFO"
```

---

## 📁 File Structure

```
ansible/
├── README.md                           # Overview
├── roles/
│   └── pote/
│       └── defaults/
│           └── main.yml                # ⭐ ALL POTE variables (200+ lines)
├── group_vars/
│   ├── all.yml                         # Common to all environments
│   ├── development.yml                 # Dev-specific (branch: dev)
│   ├── staging.yml                     # QA-specific (branch: qa)
│   └── production.yml                  # Prod-specific (branch: main)
├── inventory.example.yml               # Example inventory
└── vault.example.yml                   # Example secrets
```

---

## 🚀 How to Use

### 1. Copy to Your Ansible Project

```bash
# Copy ansible/ directory to your Ansible project
cp -r ansible/ /path/to/your/ansible/project/roles/pote/

# Or include as a submodule
git submodule add https://git.levkin.ca/ilia/POTE.git roles/pote
```

### 2. Create Inventory

```yaml
# inventory.yml
all:
  children:
    development:
      hosts:
        pote-dev:
          ansible_host: 10.0.10.100
    
    staging:
      hosts:
        pote-qa:
          ansible_host: 10.0.10.101
    
    production:
      hosts:
        pote-prod:
          ansible_host: 10.0.10.95
```

### 3. Create Vault for Secrets

```bash
# Create encrypted vault
ansible-vault create group_vars/all/vault.yml

# Add secrets:
vault_git_ssh_key: |
  -----BEGIN OPENSSH PRIVATE KEY-----
  ...
  -----END OPENSSH PRIVATE KEY-----

vault_smtp_password: "your_password"
vault_db_password_dev: "dev_pass"
vault_db_password_qa: "qa_pass"
vault_db_password_prod: "prod_pass"
```

### 4. Create Playbook

```yaml
# deploy-pote.yml
---
- name: Deploy POTE
  hosts: "{{ target_env | default('production') }}"
  become: yes
  
  roles:
    - role: base_os  # Your existing base OS role
    - role: pote     # POTE role
  
  tasks:
    - name: Display deployment info
      debug:
        msg: "Deployed POTE {{ pote_git_branch }} to {{ inventory_hostname }}"
```

### 5. Deploy

```bash
# Deploy to development
ansible-playbook -i inventory.yml deploy-pote.yml \
  --limit development \
  --ask-vault-pass

# Deploy to staging
ansible-playbook -i inventory.yml deploy-pote.yml \
  --limit staging \
  --ask-vault-pass

# Deploy to production
ansible-playbook -i inventory.yml deploy-pote.yml \
  --limit production \
  --ask-vault-pass
```

---

## 🔧 Integration with base_os Role

POTE variables are compatible with your existing `base_os` role:

```yaml
# POTE automatically sets these for base_os compatibility:
base_os_user: "{{ pote_user }}"                    # poteapp
base_os_backend_port: "{{ pote_backend_port }}"    # 8000 (future)
base_os_enable_backend: "{{ pote_enable_backend }}" # false (no HTTP yet)
base_os_enable_frontend: false                      # No frontend

# base_os should install:
base_os_packages:
  - git
  - curl
  - ca-certificates
  - openssh-server
  - sudo
  - python3
  - python3-pip
  - python3-venv
  - postgresql-client
  - libpq-dev
  - build-essential
```

---

## 📊 Variable Categories

### 1. **Project Basics** (5 vars)
- `pote_project_name`
- `pote_app_description`
- `pote_version`
- `pote_git_repo`
- `pote_git_branch`

### 2. **User & Paths** (7 vars)
- `pote_user`, `pote_group`
- `pote_user_home`, `pote_app_dir`
- `pote_venv_dir`, `pote_logs_dir`
- `pote_user_ssh_public_key`

### 3. **Python & Dependencies** (3 lists)
- `pote_python_version`
- `pote_python_packages` (5 items)
- `pote_system_packages` (8 items)

### 4. **Database** (8 vars)
- `pote_db_host`, `pote_db_port`
- `pote_db_name`, `pote_db_user`, `pote_db_password`
- `pote_database_url` (computed)
- `pote_create_database`, `pote_run_migrations`

### 5. **Email/SMTP** (6 vars)
- `pote_smtp_host`, `pote_smtp_port`
- `pote_smtp_user`, `pote_smtp_password`
- `pote_from_email`, `pote_report_recipients`

### 6. **Monitoring** (2 vars)
- `pote_market_monitor_tickers`
- `pote_alert_min_severity`

### 7. **Logging** (2 vars)
- `pote_log_level`
- `pote_log_file`

### 8. **Cron/Automation** (7 vars)
- `pote_enable_cron`
- `pote_daily_report_time`, `pote_daily_report_enabled`
- `pote_weekly_report_time`, `pote_weekly_report_enabled`
- `pote_health_check_enabled`, `pote_health_check_time`

### 9. **Deployment** (6 vars)
- `pote_deployment_strategy`
- `pote_backup_before_deploy`, `pote_backup_retention_days`
- `pote_rollback_on_failure`
- `pote_health_check_after_deploy`
- `pote_run_tests`, `pote_run_smoke_tests`

### 10. **Security** (4 vars)
- `pote_env_file_mode`
- `pote_app_dir_mode`, `pote_logs_dir_mode`
- `pote_use_vault`, `pote_vault_path`

### 11. **Feature Flags** (4 vars)
- `pote_feature_email_reports`
- `pote_feature_market_monitoring`
- `pote_feature_disclosure_correlation`
- `pote_feature_pattern_detection`

---

## 🎯 Minimal Required Variables

**Absolute minimum to deploy:**

```yaml
# Git
pote_git_repo: "gitea@10.0.30.169:ilia/POTE.git"
pote_git_branch: "main"

# Database
pote_db_password: "changeme123"

# Email
pote_smtp_password: "your_password"
```

**Everything else has sensible defaults!**

---

## 🔐 Secrets to Store in Vault

```yaml
# Required
vault_git_ssh_key: "..."
vault_smtp_password: "..."
vault_db_password_dev: "..."
vault_db_password_qa: "..."
vault_db_password_prod: "..."

# Optional
vault_ssh_public_key: "..."
vault_quiverquant_key: "..."
vault_fmp_key: "..."
```

---

## 📝 Example Playbook Tasks

```yaml
- name: Clone POTE repository
  git:
    repo: "{{ pote_git_repo }}"
    dest: "{{ pote_app_dir }}"
    version: "{{ pote_git_branch }}"
    key_file: /tmp/git_key
  become_user: "{{ pote_user }}"

- name: Create virtual environment
  command: python3 -m venv {{ pote_venv_dir }}
  args:
    creates: "{{ pote_venv_dir }}/bin/activate"
  become_user: "{{ pote_user }}"

- name: Install Python dependencies
  pip:
    requirements: "{{ pote_app_dir }}/requirements.txt"
    virtualenv: "{{ pote_venv_dir }}"
  become_user: "{{ pote_user }}"

- name: Create .env file
  template:
    src: env.j2
    dest: "{{ pote_env_file }}"
    mode: "{{ pote_env_file_mode }}"
    owner: "{{ pote_user }}"
    group: "{{ pote_group }}"

- name: Run database migrations
  command: "{{ pote_venv_dir }}/bin/alembic upgrade head"
  args:
    chdir: "{{ pote_app_dir }}"
  become_user: "{{ pote_user }}"
  when: pote_run_migrations

- name: Set up cron jobs
  cron:
    name: "POTE daily report"
    minute: "{{ pote_daily_report_time.split()[0] }}"
    hour: "{{ pote_daily_report_time.split()[1] }}"
    job: "{{ pote_venv_dir }}/bin/python {{ pote_app_dir }}/scripts/automated_daily_run.sh"
    user: "{{ pote_user }}"
  when: pote_enable_cron and pote_daily_report_enabled
```

---

## ✅ Summary

**Total variables defined:** 200+

**Categories:** 11

**Required secrets:** 5

**Minimum to deploy:** 3 variables

**Files created:**
- ✅ `ansible/roles/pote/defaults/main.yml` - Complete variable definitions
- ✅ `ansible/group_vars/all.yml` - Common variables
- ✅ `ansible/group_vars/development.yml` - Dev environment
- ✅ `ansible/group_vars/staging.yml` - QA environment
- ✅ `ansible/group_vars/production.yml` - Prod environment
- ✅ `ansible/inventory.example.yml` - Example inventory
- ✅ `ansible/vault.example.yml` - Example secrets

**Everything Ansible needs to automatically deploy POTE to dev/qa/prod!** 🚀