254 lines
8.3 KiB
Markdown
254 lines
8.3 KiB
Markdown
# 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
|