Subir archivos a "docs"

docs/DEPLOYMENT.md

@@ -0,0 +1,160 @@
+# Despliegue Local/VM
+
+Esta guia documenta el despliegue recomendado para arquitectos: una laptop o VM con Python, acceso a los catalogos/datos del proyecto y ejecucion local de Streamlit. No requiere Docker ni servicios administrados.
+
+## Requisitos
+
+- Python 3.12. En este workspace se valido con Python 3.12.13.
+- Acceso de red si se van a descargar catalogos AWS/OCI actualizados.
+- Ollama opcional para funciones LLM de mapeo o respuestas naturales.
+- Twilio opcional para WhatsApp.
+- Puerto local disponible para Streamlit, normalmente `8501`.
+- Puerto local disponible para Flask/WhatsApp, normalmente `3000`.
+
+## Instalacion
+
+Desde la raiz del proyecto:
+
+```bash
+python3.12 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+```
+
+Verifica instalacion:
+
+```bash
+python --version
+python -m pytest -q
+```
+
+## Configuracion de entorno
+
+Crea el archivo local:
+
+```bash
+cp .env.example .env
+```
+
+Variables relevantes:
+
+| Variable | Uso | Obligatoria |
+| --- | --- | --- |
+| `CLOUD_CHAT_MODEL` | Modelo Ollama para Cloud Chat. | No |
+| `CLOUD_CHAT_PROVIDER` | Provider del catalogo, hoy `aws`. | No |
+| `CLOUD_CHAT_CATALOG` | Ruta del catalogo para Cloud Chat. | No |
+| `CLOUD_CHAT_USE_LLM` | `true` para usar LLM, `false` para modo deterministico. | No |
+| `TWILIO_ACCOUNT_SID` | Cuenta Twilio para envio WhatsApp. | Solo WhatsApp |
+| `TWILIO_AUTH_TOKEN` | Token Twilio y validacion webhook. | Solo WhatsApp |
+| `TWILIO_WHATSAPP_FROM` | Numero sandbox o remitente Twilio. | Solo WhatsApp |
+| `MY_WHATSAPP_TO` | Destino default para pruebas de envio. | Solo envio |
+| `PUBLIC_WEBHOOK_URL` | URL publica exacta de `/whatsapp`. | Solo webhook |
+| `WHATSAPP_PORT` | Puerto Flask del webhook. | No |
+
+No subas `.env`. Comparte solo `.env.example`.
+
+## Iniciar GUI Streamlit
+
+Con el ambiente activado:
+
+```bash
+streamlit run cloud_conversion_ui/Home.py
+```
+
+Alternativa sin activar el ambiente:
+
+```bash
+.venv/bin/streamlit run cloud_conversion_ui/Home.py
+```
+
+En una VM, si necesitas exponerlo a otros usuarios de la red:
+
+```bash
+streamlit run cloud_conversion_ui/Home.py --server.address 0.0.0.0 --server.port 8501
+```
+
+Usa reglas de firewall o red interna para restringir acceso. La GUI no implementa autenticacion propia.
+
+## Actualizar catalogos
+
+Desde la GUI, entra a `Catalogos` y ejecuta:
+
+- `AWS Fetch`: descarga `data/raw/aws/index.json`.
+- `AWS EDA`: genera `data/catalog/aws/aws_ec2_catalog.csv` y reporte EDA.
+- `OCI Fetch`: descarga `data/raw/oci/products.json` y genera `data/catalog/oci/oci_price_list.csv`.
+
+Desde CLI:
+
+```bash
+python scripts/aws_fetch_offer.py
+python scripts/aws_eda.py
+python scripts/oci_fetch_offer.py
+```
+
+## Ejecutar comparativas
+
+Ruta recomendada:
+
+1. Abre la GUI.
+2. En `Inventario`, selecciona o sube un archivo CSV, XLS o XLSX.
+3. En `Ejecucion`, revisa parametros AWS/OCI.
+4. Ejecuta `AWS Match` y `OCI Match`.
+5. En `Dashboard`, revisa costo mensual, ahorro y cobertura.
+6. En `Logs y Artefactos`, descarga salidas.
+
+Nota importante: la GUI ejecuta matching con `move_to_done=False`. Esto permite comparar AWS y OCI sobre el mismo inventario sin moverlo automaticamente. Para archivar el inventario, usa el boton `Archivar en input/done` en la pagina `Inventario`.
+
+## Ollama opcional
+
+Los scripts pueden inferir columnas con reglas deterministicas o con LLM local. Para evitar dependencia de Ollama en ejecuciones controladas, usa `--skip-llm` en CLI o marca `Skip LLM` en la GUI.
+
+Si se usa LLM:
+
+```bash
+ollama pull llama3.1:8b
+```
+
+Luego ejecuta sin `--skip-llm` o configura el modelo en la GUI.
+
+## WhatsApp opcional
+
+Para probar envio:
+
+```bash
+python scripts/whatsapp_send.py --body "Prueba Cloud Conversion" --dry-run
+```
+
+Para iniciar el webhook Cloud Chat:
+
+```bash
+python scripts/whatsapp_chatbot.py
+```
+
+Twilio debe apuntar al `PUBLIC_WEBHOOK_URL` exacto, por ejemplo:
+
+```text
+https://tu-ngrok.ngrok-free.app/whatsapp
+```
+
+`server.py` y `send.py` son demos legacy. Para operacion real usa `scripts/whatsapp_chatbot.py` y `scripts/whatsapp_send.py`.
+
+## Troubleshooting
+
+| Sintoma | Revision |
+| --- | --- |
+| Streamlit no inicia | Confirma `streamlit==1.57.0` en `requirements.txt` y que el venv este activo. |
+| No aparecen inventarios | Coloca CSV/XLS/XLSX en `input/` o sube desde la GUI. |
+| Hay mas de un inventario en CLI | Usa `--inventory` para indicar el archivo exacto. |
+| AWS Match no encuentra candidatos | Revisa region, OS, tenancy, unit y catalogo AWS generado. |
+| OCI Match no genera BOM | Revisa que el catalogo OCI tenga SKUs Compute Standard y precios USD. |
+| LLM falla | Ejecuta con `--skip-llm` o verifica Ollama/modelo. |
+| Twilio rechaza webhook | `PUBLIC_WEBHOOK_URL` debe coincidir exactamente con la URL firmada por Twilio. |
+
+## Checklist de publicacion interna
+
+- `.env` no esta versionado.
+- No hay secretos en logs o inventarios compartidos.
+- `python -m pytest -q` pasa.
+- La GUI inicia con `streamlit run cloud_conversion_ui/Home.py`.
+- `data/` se comparte conscientemente aunque pesa aproximadamente 8 GB.
+