From aa6f6a36e62c9f84b2684cbe3c3a2935b4115950 Mon Sep 17 00:00:00 2001 From: OpenCode Date: Sun, 5 Apr 2026 23:42:10 +0200 Subject: [PATCH] Document VPS2 deployment and Forgejo setup --- .gitignore | 1 + RAG/docs/BITACORA_DISENO_RAG.md | 18 ++ RAG/docs/DESPLIEGUE_EASYPANEL.md | 254 +++++++++++++++++++++ RAG/docs/DUDAS_DESPLIEGUE_WEBFETCH_VPS2.md | 88 +++++++ docs/HISTORIAL_SESIONES.md | 7 + docs/INDICE_DOCUMENTACION.md | 53 ++++- 6 files changed, 420 insertions(+), 1 deletion(-) create mode 100644 .gitignore create mode 100644 RAG/docs/DESPLIEGUE_EASYPANEL.md create mode 100644 RAG/docs/DUDAS_DESPLIEGUE_WEBFETCH_VPS2.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..95f02ec --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +docs/ACCESOS_INFRAESTRUCTURA_LOCAL.md diff --git a/RAG/docs/BITACORA_DISENO_RAG.md b/RAG/docs/BITACORA_DISENO_RAG.md index 4ab245c..0f2835d 100644 --- a/RAG/docs/BITACORA_DISENO_RAG.md +++ b/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. diff --git a/RAG/docs/DESPLIEGUE_EASYPANEL.md b/RAG/docs/DESPLIEGUE_EASYPANEL.md new file mode 100644 index 0000000..53bcf9b --- /dev/null +++ b/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=` +- `ANSWER_PROVIDER=openrouter` +- `ANSWER_MODEL=openai/gpt-4.1-mini` +- `ANSWER_BASE_URL=https://openrouter.ai/api/v1` +- `ANSWER_API_KEY=` + +### 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.` + +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 diff --git a/RAG/docs/DUDAS_DESPLIEGUE_WEBFETCH_VPS2.md b/RAG/docs/DUDAS_DESPLIEGUE_WEBFETCH_VPS2.md new file mode 100644 index 0000000..fa5ab67 --- /dev/null +++ b/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 diff --git a/docs/HISTORIAL_SESIONES.md b/docs/HISTORIAL_SESIONES.md index a122218..bde2e47 100644 --- a/docs/HISTORIAL_SESIONES.md +++ b/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. diff --git a/docs/INDICE_DOCUMENTACION.md b/docs/INDICE_DOCUMENTACION.md index 1598f74..db9c724 100644 --- a/docs/INDICE_DOCUMENTACION.md +++ b/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