Document VPS2 deployment and Forgejo setup

.gitignore

@@ -0,0 +1 @@
+docs/ACCESOS_INFRAESTRUCTURA_LOCAL.md

RAG/docs/BITACORA_DISENO_RAG.md

@@ -237,6 +237,24 @@ La separacion operativa actual se hace por `sourceRef` y `source_id` dentro del
 
 Esto demuestra en pequeno el mismo patron que luego servira para separar clientes, proyectos o dominios dentro del mismo sistema.
 
+---
+
+### Despliegue bien integrado en EasyPanel frente a despliegue manual local
+
+**Hallazgo posterior:**
+`webfetch` funciona en `VPS2`, pero su imagen fue construida manualmente en el VPS y luego asociada a EasyPanel por nombre local de imagen.
+
+**Problema de ese patron:**
+- funciona operativamente
+- pero no queda totalmente integrado con el flujo esperado de EasyPanel para redeploy y gestion de fuente
+
+**Conclusion aplicada a `RAG`:**
+para dejar `RAG` bien integrado, conviene usar el patron esperado por EasyPanel:
+- `App Service`
+- fuente Git con `Dockerfile`, o imagen publicada en registry
+
+Esto permitira que el panel pueda redesplegar de forma coherente sin depender de una imagen local construida fuera de su flujo.
+
 **Decision complementaria sobre `document_key`:**
 Se adopta como regla base que el documento se identifique por una clave interna normalizada, preferiblemente relativa a la fuente.
 

RAG/docs/DESPLIEGUE_EASYPANEL.md

@@ -0,0 +1,254 @@
+# Despliegue en EasyPanel para VPS2
+
+**Proyecto:** Workspace de tools IA para empresas  
+**Modulo:** RAG  
+**Ultima actualizacion:** 2026-04-05  
+**Ultima modificacion por:** Agente tools IA para potenciar servicios empresariales  
+**Estado:** Base operativa definida
+
+---
+
+## Proposito
+
+Dejar documentado el patron de despliegue del servicio `RAG` dentro de EasyPanel, tomando como referencia lo ya montado y funcionando en `VPS2`, especialmente `webfetch` y `qdrant` dentro del proyecto `ia_servicios`.
+
+Este documento aplica especificamente al despliegue en `VPS2` y no debe interpretarse como una guia universal para cualquier otro servidor o cualquier otra instancia de EasyPanel.
+
+Si en el futuro se despliega en otro VPS, cloud o panel distinto, habra que revisar de nuevo red, dominios, recursos, rutas, politicas y servicios disponibles en ese entorno.
+
+---
+
+## Hallazgos confirmados en VPS2
+
+Servicios detectados en el proyecto o entorno relacionado:
+
+- `ia_servicios_webfetch`
+- `ia_servicios_qdrant`
+- `ia_servicios_postgres-ia-servicios`
+- `easypanel`
+- `traefik`
+
+Forgejo confirmado:
+
+- dominio web: `https://git.por-correo.com`
+- SSH Git: `git@git.por-correo.com` por puerto `2222`
+- el endpoint SSH ya responde correctamente para autenticacion Git
+
+Redes Docker relevantes:
+
+- `easypanel`
+- `easypanel-ia_servicios`
+
+Patron observado:
+
+- los servicios del proyecto `ia_servicios` se montan como servicios Swarm simples
+- se unen a la red global de EasyPanel y a la red overlay del proyecto
+- `webfetch` corre sin volumen persistente visible
+- `qdrant` corre con volumen persistente propio
+
+---
+
+## Como esta montado webfetch
+
+Confirmado en la revision:
+
+- imagen: `webfetch:latest`
+- puerto interno: `80`
+- variables de entorno: `WEBFETCH_API_KEY`, `PORT`, metadatos de despliegue
+- redes: `easypanel` y `easypanel-ia_servicios`
+- sin volumen persistente visible
+- expuesto por dominio publico gestionado por EasyPanel y Traefik
+
+Esto lo convierte en una buena referencia para el despliegue del backend `RAG`, con la diferencia de que `RAG` necesitara mas variables de entorno y consumira `qdrant`.
+
+### Patron real recuperado del despliegue de webfetch
+
+`webfetch` no fue construido por EasyPanel.
+
+El flujo real fue:
+
+1. Crear un directorio temporal en el VPS.
+2. Copiar alli los archivos necesarios del servicio.
+3. Construir la imagen localmente en el VPS con `docker build -t webfetch:latest .`.
+4. Forzar el servicio Swarm para reutilizar esa imagen local con `docker service update --force ia_servicios_webfetch`.
+5. Ajustar variables de entorno por CLI si hacia falta, por ejemplo la API key.
+
+### Implicacion importante
+
+- EasyPanel no generaba la imagen
+- Docker en el VPS si la generaba
+- EasyPanel solo apuntaba al nombre de imagen local `webfetch:latest`
+
+Esto explica por que el boton `Deploy` puede fallar en este patron: intenta hacer `docker pull` de una imagen que solo existe localmente en el VPS.
+
+### Lo que esto significa para RAG
+
+Hay dos caminos validos para `RAG` en `VPS2`:
+
+1. repetir el patron de `webfetch`
+- construir la imagen localmente en el VPS
+- apuntar el servicio de EasyPanel a esa imagen local
+
+2. usar un registry
+- publicar la imagen en un registry accesible
+- dejar que EasyPanel pueda redeplegar sin depender de imagen local preexistente
+
+Para robustez operativa, el segundo camino es mejor. Para velocidad de arranque, el primero se parece mas a como ya se monto `webfetch`.
+
+---
+
+## Patron correcto esperado por EasyPanel
+
+Contrastando el caso real de `webfetch` con la documentacion oficial de EasyPanel:
+
+- EasyPanel espera que un `App Service` tenga una fuente declarada
+- esa fuente puede ser:
+  - repositorio GitHub
+  - proveedor Git custom
+  - imagen Docker publicada y accesible
+- si hay `Dockerfile` en el repositorio, EasyPanel puede construir la imagen desde ese codigo
+
+### Implicacion practica
+
+El despliegue de `webfetch` funciono, pero no quedo totalmente integrado en EasyPanel porque la imagen solo existia localmente en el VPS.
+
+Eso rompe parte del flujo esperado del panel, especialmente el redeploy autonomo desde `Deploy`, porque el panel intenta hacer `pull` o reconstruir segun la fuente configurada.
+
+### Conclusion para RAG
+
+Si queremos que `RAG` quede bien integrado en EasyPanel, lo correcto no es repetir exactamente el patron manual de `webfetch`.
+
+Lo correcto es elegir uno de estos caminos:
+
+1. **App Service + repositorio Git + Dockerfile**
+- EasyPanel construye la imagen desde el codigo del repo
+- es la opcion mas integrada con el panel
+
+2. **App Service + imagen publicada en registry**
+- EasyPanel hace pull de una imagen accesible externamente
+- tambien queda bien integrado
+
+El patron de imagen solo local en el VPS debe considerarse util como solucion temporal o de emergencia, pero no como la forma final deseable si queremos integracion completa con EasyPanel.
+
+Dado que Forgejo ya esta operativo en `git.por-correo.com`, el camino preferente para `RAG` pasa a ser:
+
+- subir el codigo del modulo a un repo propio en Forgejo
+- conectar EasyPanel por Git SSH
+- dejar que el `App Service` construya desde el `Dockerfile`
+
+---
+
+## Como esta montado qdrant
+
+Confirmado en la revision:
+
+- imagen: `qdrant/qdrant:v1.15`
+- puerto interno: `6333`
+- volumen persistente: `ia_servicios_qdrant_storage`
+- mount path: `/qdrant/storage`
+- redes: `easypanel` y `easypanel-ia_servicios`
+
+Dato importante para `RAG`:
+
+- al vivir en la misma red del proyecto, `RAG` no deberia consumir `qdrant` por dominio publico
+- lo correcto es usar la conectividad interna del proyecto, por ejemplo `http://qdrant:6333`
+
+---
+
+## Patron recomendado para desplegar RAG en VPS2
+
+### Tipo de servicio
+
+- servicio HTTP dentro del proyecto `ia_servicios`
+- montado como app en EasyPanel
+
+### Imagen
+
+- imagen generada desde el `Dockerfile` del modulo `RAG`
+- etiqueta recomendada inicial: `rag-service:local` o una equivalente en registry cuando se publique
+
+### Puerto interno
+
+- `3000`
+
+### Redes esperadas
+
+- `easypanel`
+- `easypanel-ia_servicios`
+
+### Variables de entorno recomendadas
+
+- `PORT=3000`
+- `NODE_ENV=production`
+- `QDRANT_URL=http://qdrant:6333`
+- `QDRANT_API_KEY=` si se activa mas adelante
+- `QDRANT_COLLECTION=rag_chunks`
+- `EMBEDDING_PROVIDER=openrouter`
+- `EMBEDDING_MODEL=qwen/qwen3-embedding-8b`
+- `EMBEDDING_BASE_URL=https://openrouter.ai/api/v1`
+- `EMBEDDING_API_KEY=<valor real>`
+- `ANSWER_PROVIDER=openrouter`
+- `ANSWER_MODEL=openai/gpt-4.1-mini`
+- `ANSWER_BASE_URL=https://openrouter.ai/api/v1`
+- `ANSWER_API_KEY=<valor real>`
+
+### Volumen persistente
+
+- no es obligatorio para la app RAG en esta fase
+- el estado persistente principal vive en `qdrant`
+
+---
+
+## Dominio esperado en VPS2
+
+Si se sigue el patron actual del proyecto, un dominio temporal de EasyPanel para `RAG` podria verse parecido a:
+
+- `ia-servicios-rag.<subdominio easypanel>`
+
+Mas adelante podra moverse a un dominio propio o subdominio dedicado si conviene.
+
+---
+
+## Recomendacion operativa para VPS2
+
+Para el despliegue real de `RAG` en EasyPanel:
+
+1. Construir o subir la imagen del servicio.
+2. Crear el servicio en el proyecto `ia_servicios`.
+3. Configurar el puerto interno `3000`.
+4. Configurar variables de entorno.
+5. Usar `QDRANT_URL=http://qdrant:6333` para aprovechar la red interna.
+6. Exponer dominio solo para el backend `RAG`, no para la conexion interna con `qdrant`.
+7. Probar `GET /health`, `POST /retrieve` y `POST /answer` desde el dominio publicado.
+
+### Recomendacion especifica segun el patron actual del VPS2
+
+Si se quiere ir rapido y replicar el modelo de `webfetch`:
+
+1. construir la imagen `RAG` directamente en el VPS2
+2. etiquetarla con un nombre local estable, por ejemplo `rag-service:latest`
+3. crear o actualizar el servicio de EasyPanel para usar esa imagen local
+
+Si se quiere un despliegue mas mantenible a medio plazo:
+
+1. publicar la imagen en registry
+2. configurar EasyPanel para tirar de esa imagen publicada
+3. evitar depender de builds manuales dentro del VPS
+
+Si se quiere ademas aprovechar mejor la integracion del panel:
+
+1. montar `RAG` como `App Service`
+2. conectar el codigo fuente por Git
+3. usar el `Dockerfile` del modulo `RAG`
+4. dejar que EasyPanel gestione build y redeploy segun su flujo esperado
+
+---
+
+## Observacion importante
+
+El servicio ya esta funcional en local con `Qdrant` remoto y con modos `documental` y `codigo` probados.
+
+El siguiente salto natural es solo operativo:
+
+- construir la imagen Docker sin errores de red
+- montarla en EasyPanel siguiendo este patron

RAG/docs/DUDAS_DESPLIEGUE_WEBFETCH_VPS2.md

@@ -0,0 +1,88 @@
+# Dudas sobre despliegue de webfetch en VPS2
+
+**Proyecto:** Workspace de tools IA para empresas  
+**Modulo:** RAG  
+**Contexto:** Preparacion del despliegue de `RAG` en `VPS2` dentro de EasyPanel  
+**Objetivo:** Aclarar exactamente como fue montado `webfetch` para reutilizar el patron correcto en `ia_servicios`
+
+---
+
+## Instruccion
+
+Este documento esta pensado para que otro agente o compañero rellene la informacion faltante sobre el despliegue real de `webfetch` en `VPS2`.
+
+La idea es reducir incertidumbre antes de montar `RAG` en EasyPanel siguiendo el mismo patron operativo.
+
+---
+
+## Preguntas a responder
+
+1. `webfetch` se creo desde imagen ya construida o desde codigo fuente con build en EasyPanel?
+
+Respuesta: Se construyo como imagen local en el VPS. EasyPanel no genero la imagen.
+
+2. Si se uso imagen ya construida, donde esta alojada?
+
+Respuesta: La imagen quedo alojada localmente en Docker del VPS con la etiqueta `webfetch:latest`.
+
+3. Si se hizo build en EasyPanel, desde donde se obtuvo el codigo?
+- repositorio git
+- zip
+- subida manual
+- otra via
+
+Respuesta: No se hizo build en EasyPanel. Se copiaron archivos al VPS y se construyo alli manualmente.
+
+4. Existe algun `Dockerfile` o configuracion especial usada para `webfetch`?
+
+Respuesta: Si. Se uso un `Dockerfile` simple basado en `node:22-alpine`, copiando `package.json`, `package-lock.json`, `server.js` y `synonym-provider.js`, exponiendo el puerto `80` y arrancando con `npm start`.
+
+5. Se uso algun dominio o ruta especial en EasyPanel aparte del dominio generado automaticamente?
+
+Respuesta:
+
+6. `webfetch` depende de algun servicio interno del proyecto `ia_servicios` o funciona completamente aislado?
+
+Respuesta:
+
+7. Hay variables de entorno importantes aparte de `WEBFETCH_API_KEY` y `PORT`?
+
+Respuesta: Tambien aparecen metadatos de despliegue como `DEPLOY_TIMESTAMP` y `GIT_SHA`, pero la variable funcional importante recuperada fue `WEBFETCH_API_KEY`.
+
+8. Hay algun volumen, bind mount o ruta persistente asociada a `webfetch` aunque no aparezca claramente en la inspeccion inicial?
+
+Respuesta: En la inspeccion realizada no aparece volumen persistente visible para `webfetch`.
+
+9. El servicio tiene alguna configuracion especial de EasyPanel respecto a:
+- healthcheck
+- restart policy
+- resources
+- command
+- entrypoint
+- publish settings
+
+Respuesta: Se observo `restart policy` on-failure y despliegue Swarm simple en las redes `easypanel` y `easypanel-ia_servicios`. No se confirmo healthcheck personalizado ni recursos especiales.
+
+10. Hay alguna razon por la que `webfetch` se monto asi y no de otra manera?
+
+Respuesta: La razon practica fue rapidez y control local del build. Como contrapartida, EasyPanel no puede redeplegar correctamente si intenta hacer pull de una imagen que solo existe en el VPS.
+
+11. Si hoy hubiera que redeplegar `webfetch` desde cero en `VPS2`, cuales serian los pasos exactos?
+
+Respuesta:
+1. Preparar un directorio temporal en el VPS.
+2. Copiar los archivos necesarios del servicio.
+3. Ejecutar `docker build -t webfetch:latest .`.
+4. Ejecutar `docker service update --force ia_servicios_webfetch`.
+5. Ajustar variables si hace falta, por ejemplo `docker service update --env-add WEBFETCH_API_KEY=... ia_servicios_webfetch`.
+
+12. Que aspectos de ese despliegue deberian reutilizarse tal cual para `RAG` y cuales no?
+
+Respuesta:
+Reutilizar:
+- build local en VPS como via rapida inicial
+- redes del proyecto `ia_servicios`
+- variables por entorno
+
+No reutilizar necesariamente como solucion final:
+- depender de imagen solo local si se quiere redeploy limpio desde EasyPanel

docs/HISTORIAL_SESIONES.md

@@ -49,9 +49,16 @@ Este archivo registra agentes y sesiones de trabajo de este workspace.
 - Limpieza de la coleccion `rag_chunks`, reingesta separada de `docs/` y `RAG/docs/`, y prueba satisfactoria de consultas acotadas por `scope` a cada fuente.
 - Implementacion completa del modo `codigo`, incluyendo ingesta de `RAG/src/`, chunking semantico por bloques top-level, retrieve filtrado y respuesta con referencias de lineas.
 - Prueba satisfactoria del modo `codigo` con una consulta real sobre la construccion de `source_id` en el sistema.
+- Auditoria inicial de `VPS2`, identificando recursos, servicios del proyecto `ia_servicios`, patron de montaje de `webfetch` y forma recomendada de desplegar `RAG` en EasyPanel.
+- Creacion de `RAG/docs/DESPLIEGUE_EASYPANEL.md` con la base de despliegue del servicio en el VPS.
+- Aclaracion de que la guia de despliegue en EasyPanel aplica especificamente a `VPS2` y creacion de `RAG/docs/DUDAS_DESPLIEGUE_WEBFETCH_VPS2.md` para recopilar informacion faltante del despliegue de `webfetch`.
+- Incorporacion del patron real de despliegue de `webfetch` en `VPS2`, dejando documentado que la imagen se construyo localmente en el VPS y no desde EasyPanel.
+- Contraste del patron manual de `webfetch` con la documentacion oficial de EasyPanel, dejando definido que `RAG` deberia montarse como `App Service` con fuente Git o imagen publicada para quedar bien integrado.
+- Verificacion de que Forgejo ya esta operativo en `git.por-correo.com` y que el acceso Git por SSH en puerto `2222` responde correctamente, dejando preparado el camino de despliegue integrado para `RAG`.
 - Reorganizacion de RAG como modulo raiz independiente con documentacion propia en `RAG/docs/`.
 - Ajuste del indice documental global para reflejar la separacion entre documentacion global y documentacion por tool.
 - Creacion de `docs/TASK.md` para descomponer lineas de trabajo amplias en puntos de analisis y acuerdos.
+- Creacion de `docs/ACCESOS_INFRAESTRUCTURA_LOCAL.md` para recoger accesos de VPS2, EasyPanel y servicios de infraestructura del workspace.
 
 #### Estado final:
 - Documentacion base alineada con este workspace.

docs/INDICE_DOCUMENTACION.md

@@ -118,6 +118,23 @@ Descomponer lineas de trabajo amplias en bloques de analisis, decisiones y acuer
 
 ---
 
+### `ACCESOS_INFRAESTRUCTURA_LOCAL.md`
+
+**Ubicacion:** `docs/ACCESOS_INFRAESTRUCTURA_LOCAL.md`
+
+**Proposito:**
+Registrar accesos temporales y datos de infraestructura necesarios para auditoria, despliegue y revision operativa del workspace.
+
+**Cuando leerlo:**
+- al necesitar acceder al VPS, EasyPanel o servicios relacionados
+- al revisar como estan montados servicios de infraestructura como webfetch o qdrant
+
+**Cuando actualizarlo:**
+- cuando se añadan o cambien accesos de infraestructura
+- cuando se incorporen nuevos entornos o servicios relevantes
+
+---
+
 ### `RAG/docs/SISTEMA_RAG_BASE.md`
 
 **Ubicacion:** `RAG/docs/SISTEMA_RAG_BASE.md`
@@ -221,6 +238,40 @@ Documentar el stack tecnico minimo acordado para construir la primera version fu
 
 ---
 
+### `RAG/docs/DESPLIEGUE_EASYPANEL.md`
+
+**Ubicacion:** `RAG/docs/DESPLIEGUE_EASYPANEL.md`
+
+**Proposito:**
+Documentar el patron de despliegue del modulo RAG en EasyPanel tomando como referencia los servicios ya montados en `ia_servicios`.
+
+**Cuando leerlo:**
+- al preparar el despliegue de `RAG` en VPS2
+- al revisar como conectarlo correctamente con `qdrant` y el proyecto `ia_servicios`
+
+**Cuando actualizarlo:**
+- cuando cambie el patron de despliegue en EasyPanel
+- cuando el servicio `RAG` quede finalmente publicado y probado en el VPS
+
+---
+
+### `RAG/docs/DUDAS_DESPLIEGUE_WEBFETCH_VPS2.md`
+
+**Ubicacion:** `RAG/docs/DUDAS_DESPLIEGUE_WEBFETCH_VPS2.md`
+
+**Proposito:**
+Recoger dudas concretas sobre como se desplego `webfetch` en `VPS2` para reutilizar el patron correcto al publicar `RAG`.
+
+**Cuando leerlo:**
+- al pedir informacion a otro agente o compañero sobre el despliegue actual de `webfetch`
+- al preparar el despliegue de `RAG` siguiendo el patron de `ia_servicios`
+
+**Cuando actualizarlo:**
+- cuando se reciban respuestas sobre el despliegue de `webfetch`
+- cuando las dudas queden resueltas y sirvan para desplegar `RAG`
+
+---
+
 ### `sesion_actual_opencode.md`
 
 **Ubicacion:** `docs/sesion_actual_opencode.md`
@@ -247,4 +298,4 @@ Instruccion universal para detectar la sesion activa de OpenCode del workspace a
 
 ## Estadistica global
 
-**Total de documentos indexados:** 12
+**Total de documentos indexados:** 15