POTE/ANSIBLE_INTEGRATION.md

🤖 Ansible Integration for POTE

Quick Reference: What Ansible Needs to Know

📋 Complete Variable List

# =============================================================================
# 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

# 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

# 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

# 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

# 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

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

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

# 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

# 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

- 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! 🚀