Cloud-Conversion/docs/DEPLOYMENT.md

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:

python3.12 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Verifica instalacion:

python --version
python -m pytest -q

Configuracion de entorno

Crea el archivo local:

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:

streamlit run cloud_conversion_ui/Home.py

Alternativa sin activar el ambiente:

.venv/bin/streamlit run cloud_conversion_ui/Home.py

En una VM, si necesitas exponerlo a otros usuarios de la red:

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:

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:

ollama pull llama3.1:8b

Luego ejecuta sin --skip-llm o configura el modelo en la GUI.

WhatsApp opcional

Para probar envio:

python scripts/whatsapp_send.py --body "Prueba Cloud Conversion" --dry-run

Para iniciar el webhook Cloud Chat:

python scripts/whatsapp_chatbot.py

Twilio debe apuntar al PUBLIC_WEBHOOK_URL exacto, por ejemplo:

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.