paco/rag-service
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
rag-service/RAG/docs/DESPLIEGUE_EASYPANEL.md
OpenCode aa6f6a36e6 Document VPS2 deployment and Forgejo setup
2026-04-05 23:42:10 +02:00

8.3 KiB
Raw Blame History

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
  1. 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
  1. 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