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
Paco POR-CORREO b9a37f27c9 Restructure repo: move RAG content to repo root 
- RAG/ subfolder content promoted to repo root (git detected as renames)
- Remove parent-level docs/ and .gitignore from tracking (not part of RAG project)
- Add .atl/ to .gitignore (local agent caches)
- No history rewrite; prior commits preserved as-is
2026-07-21 22:11:28 +02:00

4.1 KiB
Raw Permalink Blame History

Metodologia de iteracion y redeploy del RAG

Proyecto: Workspace de tools IA para empresas
Modulo: RAG
Ultima actualizacion: 2026-04-06
Ultima modificacion por: Agente tools IA para potenciar servicios empresariales
Estado: Activa

Proposito

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

  • implementar mejoras del RAG
  • validarlas localmente
  • 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 localmente antes de tocar produccion
  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. Validacion local obligatoria

Antes de pedir redeploy, se valida en local.

Minimo esperado:

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

Y si aplica, pruebas HTTP locales contra:

  • /health
  • /ingest
  • /retrieve
  • /answer
  • /chat
  • endpoints de logs

No se debe pedir deploy al usuario sin haber comprobado antes que la mejora compila y que el flujo principal funciona en local.

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
  • validados en local
  • 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
  • el flujo nuevo ha sido probado localmente
  • la documentacion minima esta actualizada
  • el commit y push ya estan hechos
  • no se han subido secretos por error

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