paco/rag-service
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
rag-service/docs/METODOLOGIA_ITERACION_Y_REDEPLOY.md

4.4 KiB
Raw Blame History

Metodologia de iteracion y redeploy del RAG

Proyecto: Workspace de tools IA para empresas
Modulo: RAG
Ultima actualizacion: 2026-09-08 Ultima modificacion por: Agente RAG 2 Estado: Activa

Proposito

Dejar explicado de forma explicita el flujo de trabajo que se esta siguiendo para:

  • implementar mejoras del RAG
  • comprobar localmente que compilan y mantienen consistencia estatica
  • subir solo los cambios adecuados al repo propio
  • avisar al usuario cuando ya solo queda hacer Deploy en EasyPanel

La idea es que futuros agentes o nuevas sesiones no tengan que redescubrir este proceso.

Principio general

El flujo correcto que ya esta funcionando bien es este:

  1. implementar cambios en local
  2. validar compilacion y consistencia estatica
  3. documentar lo relevante
  4. hacer commit y push solo de lo que debe versionarse
  5. avisar al usuario de que ya puede hacer Deploy en EasyPanel
  6. probar el resultado desplegado en produccion

Flujo operativo paso a paso

1. Implementacion local

Los cambios se hacen en el workspace local, dentro del modulo:

RAG/

Esto incluye:

  • backend
  • playground
  • documentacion del modulo

2. Comprobacion local obligatoria

Antes de pedir redeploy, se comprueba en local que el proyecto compila y que los artefactos estaticos son coherentes.

Minimo esperado:

cd /home/pancho/Documentos/Empresa/Desarrollo/IA/RAG
npm run build

Tambien se pueden ejecutar comprobaciones estaticas que no levanten el servicio, como validar la estructura de un contrato OpenAPI o contrastar rutas documentadas.

No se levantan flujos ni servicios locales para validacion funcional. Las pruebas HTTP se realizan despues de publicar, contra el entorno real de produccion.

3. Documentar antes de cerrar el bloque

Si el cambio introduce una mejora real o un comportamiento nuevo, hay que dejarlo reflejado en la documentacion adecuada.

Documentos tipicos a revisar:

  • RAG/docs/API_RAG.md
  • RAG/docs/PLAYGROUND.md
  • RAG/docs/LOGS_EVALUACION.md
  • RAG/docs/DESPLIEGUE_EASYPANEL.md
  • docs/HISTORIAL_SESIONES.md

Objetivo:

  • que otros agentes entiendan el cambio sin tener que inferirlo del codigo

4. Separar versionable de sensible

Antes de commitear, revisar que no entren en Git cambios sensibles o aun no cerrados.

No subir:

  • .env.local
  • .env.easypanel.local
  • accesos o secretos
  • respaldos locales

Solo subir:

  • codigo
  • docs sin secretos
  • cambios de UX/API realmente listos para produccion

5. Commit y push

El commit se hace en el repo local del workspace y luego se sube al repo propio en Forgejo.

Remote actual:

ssh://git@git.por-correo.com:2222/paco/rag-service.git

Regla importante:

  • usar solo la configuracion local del repo
  • no tocar git config --global

6. Aviso al usuario

Cuando los cambios ya estan:

  • implementados
  • compilados y comprobados estaticamente
  • documentados
  • subidos al repo

entonces se avisa al usuario con un mensaje claro de este tipo:

  • ya esta subido
  • commit: <hash>
  • ya puedes darle a Deploy en EasyPanel

La idea es que el usuario no tenga que adivinar si falta algo mas.

7. Redeploy en EasyPanel

El usuario hace Deploy en EasyPanel para que el servicio:

  • coja el ultimo commit del repo
  • reconstruya desde Dockerfile
  • redepliegue la app

No hace falta reconstruir a mano en el VPS como se hizo antiguamente con webfetch.

8. Validacion en produccion

Tras el deploy, hay que probar el dominio publico:

https://rag.por-correo.com

Probar segun aplique:

  • health
  • funcionamiento del playground
  • consultas documentales
  • consultas de codigo
  • logs
  • uploads
  • bootstrap
  • chat

Criterio de corte

Un agente no deberia decir "haz deploy" si no se cumplen estas condiciones:

  • compila en local
  • las comprobaciones estaticas aplicables son correctas
  • la documentacion minima esta actualizada
  • el commit y push ya estan hechos
  • no se han subido secretos por error

La validacion funcional del flujo se completa despues del deploy y exclusivamente en produccion.

Resultado esperado de esta metodologia

Aplicando siempre este flujo se consigue:

  • menos redeploys innecesarios
  • menos pruebas rotas en produccion
  • mejor continuidad entre agentes
  • cambios mas explicables y revisables
  • una forma estable de trabajar que ya ha demostrado funcionar bien en este workspace