Guía Completa para Instalar Onyx con Docker

Onyx es una plataforma de inteligencia artificial de código abierto diseñada para conectar modelos de lenguaje con documentos, aplicaciones y fuentes de conocimiento. Puede utilizarse como chat para equipos, buscador empresarial, sistema RAG y espacio de trabajo con agentes y herramientas.

La plataforma puede contratarse como servicio administrado, pero también puede desplegarse en infraestructura propia. Para este último caso, Docker Compose es uno de los métodos más accesibles, ya que permite ejecutar la interfaz, la API, las bases de datos, los procesos de indexación y el resto de los componentes sin instalar manualmente todas sus dependencias.

En esta guía veremos cómo instalar Onyx con Docker, qué diferencias existen entre los modos Lite y Standard, cómo administrar los contenedores y qué medidas debes aplicar antes de publicar la instancia en Internet.

Qué es Onyx y qué servicios puede conectar

Onyx es una plataforma de chat y búsqueda empresarial que permite consultar información procedente de documentos y aplicaciones mediante modelos de inteligencia artificial. Puede conectarse con proveedores comerciales y con modelos alojados en infraestructura propia.

Entre sus funciones principales se encuentran:

• Chat con modelos de diferentes proveedores.
• Agentes y herramientas capaces de ejecutar acciones.
• Conectores para sincronizar fuentes de conocimiento.
• Búsqueda híbrida mediante palabras clave y vectores.
• Respuestas RAG fundamentadas en documentos.
• Investigación profunda y búsqueda web.
• Integración con herramientas mediante acciones y MCP.
• Carga de archivos y organización mediante proyectos.
• Administración de usuarios y sistemas de autenticación.

Onyx no incluye necesariamente el modelo generativo que utilizarás. Después de instalarlo tendrás que configurar un proveedor como OpenAI, Anthropic, Gemini, Ollama, LiteLLM o vLLM.

Onyx Lite o Standard: qué versión instalar

El instalador actual permite elegir entre dos modos. La decisión es importante porque cada uno despliega una arquitectura y unas funciones diferentes.

Característica	Onyx Lite	Onyx Standard
Chat con modelos	Sí	Sí
Agentes y herramientas	Sí	Sí
Carga de archivos	Sí	Sí
Proyectos	Sí	Sí
Conectores con fuentes externas	No	Sí
Indexación y búsqueda RAG	No	Sí
OpenSearch	No	Sí
Redis	No	Sí
Servidores de modelos para indexación	No	Sí
Procesos en segundo plano	Integrados en la API	Contenedores independientes
Uso recomendado	Pruebas, chat y equipos pequeños	RAG, conectores y organizaciones

Onyx Lite es la mejor opción para probar la plataforma, utilizar sus funciones de chat o trabajar en un servidor con pocos recursos. Almacena archivos, caché y sesiones en PostgreSQL y no ejecuta la infraestructura completa de búsqueda.

Onyx Standard está pensado para utilizar conectores, sincronizar documentación y construir un sistema de búsqueda empresarial. Necesita considerablemente más memoria y almacenamiento porque añade OpenSearch, Redis, procesos en segundo plano, almacenamiento de objetos y servidores utilizados durante la indexación.

Requisitos para instalar Onyx con Docker

Onyx puede ejecutarse en Linux, macOS o Windows mediante Docker. Para un servidor de producción suele ser preferible utilizar una distribución Linux actualizada.

Los requisitos oficiales dependen del modo seleccionado:

Modo	CPU mínima	RAM mínima	Disco mínimo	Configuración preferida
Onyx Lite	2 vCPU	2 GB	10 GB	4 vCPU, 4 GB de RAM y 50 GB
Onyx Standard	4 vCPU	10 GB	32 GB más el espacio de los datos indexados	8 vCPU o más y 16 GB de RAM o más

En el modo Standard, la documentación recomienda calcular aproximadamente el tamaño de los documentos indexados y añadir un margen amplio. El consumo real depende de la cantidad de contenido, los embeddings, la concurrencia y la configuración de OpenSearch.

Antes de comenzar necesitas:

• Una cuenta con permisos para administrar el servidor.
• Docker Engine y el complemento Docker Compose.
• Conexión a Internet para descargar imágenes y modelos.
• Git si vas a realizar la instalación manual.
• Python y uv si quieres instalar directamente Onyx CLI.
• Un dominio y acceso a su configuración DNS si publicarás la aplicación.

Comprueba Docker y Compose mediante:

docker --version
docker compose version

En Linux también debes verificar que tu usuario pueda ejecutar Docker o utilizar sudo cuando resulte necesario.

Cómo instalar Onyx con el instalador recomendado

La forma recomendada actualmente es utilizar el instalador guiado incluido en Onyx CLI. Este comprueba los recursos del equipo, permite elegir entre Lite y Standard, descarga las imágenes, inicia los contenedores y espera hasta que todos los servicios estén disponibles.

Si ya tienes instalado uv, ejecuta:

uv tool install onyx-cli
onyx-cli deploy install

El asistente te preguntará:

• Qué modo quieres instalar: Lite o Standard.
• Qué versión de Onyx quieres desplegar.
• Qué configuración debe utilizar el entorno.

En una instalación nueva, los archivos del despliegue se guardan dentro de:

~/.config/onyx

Este directorio contiene la configuración utilizada para administrar el stack. No debes confundirlo con onyx_data, una carpeta que creaban las versiones anteriores del instalador. Onyx CLI puede detectar y adoptar esos despliegues antiguos, pero ya no es la ruta predeterminada para una instalación nueva.

Cómo instalar Onyx con el script oficial

También puedes utilizar el comando publicado en la página oficial:

curl -fsSL https://onyx.app/install_onyx.sh | bash

Este script es un envoltorio del instalador de Onyx CLI. Por tanto, produce el mismo tipo de despliegue guiado y ya no debe describirse como un sistema independiente.

Antes de ejecutar directamente cualquier script descargado desde Internet, puedes guardarlo y revisar su contenido:

curl -fsSLo install_onyx.sh https://onyx.app/install_onyx.sh
less install_onyx.sh
bash install_onyx.sh

El instalador comprueba el entorno, instala Docker en sistemas Linux compatibles cuando resulta necesario y espera hasta que los contenedores estén saludables.

Cuando termine, mostrará la dirección desde la que puedes acceder. En una instalación local sin dominio suele ser:

http://localhost:3000

Si Onyx se ejecuta en otro servidor de la red, sustituye localhost por la dirección IP correspondiente. No expongas el puerto públicamente sin configurar autenticación y HTTPS.

Cómo instalar Onyx manualmente con Docker Compose

La instalación manual resulta útil si quieres revisar directamente los archivos de Compose o integrar Onyx en un flujo de despliegue propio. Sin embargo, exige administrar las actualizaciones y los cambios de configuración por tu cuenta.

Primero clona el repositorio oficial:

git clone --depth 1 https://github.com/onyx-dot-app/onyx.git
cd onyx/deployment/docker_compose

Para iniciar el despliegue Standard con las imágenes publicadas:

docker compose up -d

Si quieres compilar las imágenes desde el código fuente:

docker compose up -d --build --force-recreate

Compilar desde el código consume más tiempo y recursos. Para una instalación normal es preferible utilizar las imágenes oficiales ya publicadas.

Después de iniciar los contenedores, Onyx necesita completar su proceso de preparación. Comprueba su estado con:

docker compose ps

Para seguir los registros:

docker compose logs -f

Cuando todos los servicios estén preparados, abre:

http://localhost:3000

Cómo desplegar Onyx Lite manualmente

Onyx Lite se activa mediante un archivo de Compose adicional que deshabilita los servicios innecesarios:

docker compose \
  -f docker-compose.yml \
  -f docker-compose.onyx-lite.yml \
  up -d

Este modo inicia solamente los servicios esenciales:

• api_server, que también gestiona el trabajo en segundo plano.
• web_server, correspondiente a la interfaz.
• relational_db, basado en PostgreSQL.
• nginx, que actúa como proxy inverso.

Lite no incorpora conectores, OpenSearch ni búsqueda RAG sobre fuentes sincronizadas. Puedes cargar archivos y utilizar proyectos, pero no sustituye al despliegue Standard cuando necesitas indexar documentación procedente de aplicaciones externas.

Qué servicios utiliza Onyx Standard

La arquitectura exacta puede cambiar entre versiones, por lo que no conviene copiar un archivo Compose antiguo ni fijar manualmente imágenes de PostgreSQL, Redis u otros componentes.

En términos generales, Onyx Standard incluye:

• Un servidor de API con la lógica principal.
• Una interfaz web.
• PostgreSQL como base de datos relacional.
• Procesos en segundo plano para conectores e indexación.
• Redis para caché y sesiones.
• OpenSearch para búsqueda vectorial y por palabras clave.
• Servidores de modelos utilizados durante la indexación y recuperación.
• Almacenamiento de objetos mediante MinIO o un backend compatible.
• Nginx como proxy inverso.

Utiliza siempre los archivos incluidos con la versión de Onyx que estés instalando. Cambiar individualmente las versiones de las bases de datos puede provocar incompatibilidades o migraciones fallidas.

Cómo completar la configuración inicial

La primera persona que se registre en una instalación nueva se convierte en administradora. Por ello, debes completar este paso antes de permitir que otras personas accedan al servidor.

Después de iniciar sesión:

1. Crea una contraseña robusta para la cuenta administradora.
2. Entra en el panel de administración.
3. Configura un proveedor de modelos de lenguaje.
4. Añade las credenciales correspondientes.
5. Selecciona un modelo predeterminado.
6. Realiza una conversación de prueba.
7. Si utilizas Standard, crea un conector y comprueba la indexación.

Onyx puede trabajar con servicios comerciales y con servidores propios como Ollama, vLLM o LiteLLM. El alojamiento propio de Onyx no implica automáticamente que el modelo también sea local: si configuras OpenAI, Anthropic o Gemini, las solicitudes necesarias se enviarán a ese proveedor.

Cómo administrar Onyx mediante la CLI

Una ventaja del instalador actual es que proporciona comandos específicos para gestionar todo el ciclo de vida del despliegue:

onyx-cli deploy status
onyx-cli deploy logs
onyx-cli deploy stop
onyx-cli deploy upgrade

Sus funciones principales son:

• status: comprueba el estado de los servicios.
• logs: muestra los registros del despliegue.
• stop: detiene los contenedores sin desinstalarlos.
• upgrade: actualiza la instalación administrada.
• uninstall: elimina el despliegue.

No ejecutes uninstall para resolver un error temporal. Antes de cualquier eliminación, comprueba qué datos y volúmenes se conservarán y realiza una copia de seguridad independiente.

Cómo actualizar una instalación manual

Si administras directamente los archivos de Docker Compose, revisa las notas de la nueva versión antes de actualizar. Después, descarga los cambios del repositorio y las imágenes correspondientes.

Desde el directorio del despliegue, el proceso habitual incluye:

git pull
docker compose pull
docker compose up -d

No utilices automáticamente una versión nueva en producción sin probarla. Algunas actualizaciones pueden incluir migraciones de base de datos, cambios en variables de entorno o modificaciones en los servicios.

Para una instalación creada mediante Onyx CLI, utiliza preferentemente:

onyx-cli deploy upgrade

Persistencia y copias de seguridad

Docker Compose utiliza volúmenes para conservar la base de datos, los índices, los archivos y otros datos después de recrear los contenedores. Sin embargo, un volumen persistente no equivale a una copia de seguridad.

Antes de actualizar o modificar el despliegue:

• Haz una copia de la configuración guardada en ~/.config/onyx.
• Respalda PostgreSQL mediante una herramienta compatible con la versión instalada.
• Conserva los datos del backend de archivos o almacenamiento de objetos.
• Guarda las variables de entorno y secretos necesarios para recuperar el servicio.
• Comprueba periódicamente que las copias pueden restaurarse.
• Almacena al menos una copia fuera del servidor principal.

Algunas fuentes conectadas pueden volver a indexarse, pero la base de datos contiene usuarios, configuración, conversaciones y otros datos que no deben darse por recuperables sin una copia.

Cómo configurar un dominio y HTTPS

Si Onyx será accesible desde Internet, configura un dominio cuyo registro DNS apunte a la IP pública del servidor. Después establece la variable:

WEB_DOMAIN=onyx.ejemplo.com

El repositorio incluye un script para obtener un certificado de Let’s Encrypt en despliegues Docker:

./init-letsencrypt.sh

Antes de ejecutarlo, revisa los archivos de entorno y comprueba que el dominio resuelve correctamente hacia el servidor. También deben estar disponibles los puertos 80 y 443.

No publiques directamente una instancia de producción mediante una dirección como http://IP:3000. Sin HTTPS, las credenciales y los datos pueden quedar expuestos durante el tránsito.

Cómo proteger Onyx antes de publicarlo

La autenticación mediante correo y contraseña está habilitada de forma predeterminada. La primera cuenta registrada recibe permisos de administración.

Para una instalación utilizada por un equipo:

• Registra inmediatamente la cuenta administradora.
• Utiliza una contraseña única y robusta.
• Restringe el acceso mediante el cortafuegos.
• Activa HTTPS antes de permitir conexiones externas.
• Configura OAuth, OIDC o SAML cuando resulte adecuado.
• Limita los dominios de correo permitidos.
• Desactiva el registro abierto cuando ya no sea necesario.
• Protege las claves de los proveedores de modelos y conectores.
• Actualiza Onyx, Docker y el sistema operativo.
• Revisa los permisos de agentes, acciones y herramientas MCP.

Las versiones actuales permiten configurar parte de la seguridad desde el panel de administración. En entornos empresariales, algunas funciones avanzadas como RBAC, sincronización de permisos o cifrado adicional de secretos pueden requerir la edición Enterprise.

Cómo vigilar el consumo de almacenamiento

En el modo Standard, OpenSearch almacena los índices utilizados para la búsqueda. Si el disco alcanza el umbral crítico de ocupación —un 95 % de forma predeterminada— OpenSearch puede marcar los índices como solo lectura y detener las escrituras.

Comprueba periódicamente el espacio disponible:

df -h
docker system df

También puedes revisar el tamaño de los volúmenes y eliminar imágenes de Docker que ya no se utilicen:

docker image prune

Este comando elimina imágenes colgantes, pero debes revisar siempre lo que va a eliminarse. No utilices comandos agresivos de limpieza de Docker en un servidor de producción sin comprobar los contenedores, imágenes y volúmenes afectados.

¿Se puede instalar Onyx desde Plesk?

Plesk permite crear y administrar contenedores individuales, pero Onyx es un stack compuesto por varios servicios, redes, dependencias y volúmenes. Reconstruirlo contenedor por contenedor desde la interfaz de Plesk resulta propenso a errores y dificulta las actualizaciones.

Si tu servidor utiliza Plesk, es preferible:

1. Acceder al servidor mediante SSH.
2. Comprobar que Docker y Docker Compose están disponibles.
3. Instalar Onyx mediante Onyx CLI o los archivos oficiales de Compose.
4. Utilizar Plesk únicamente para el dominio, DNS o proxy si sabes integrar correctamente ambos sistemas.

Antes de utilizar esta combinación, comprueba que el proveedor del servidor permite administrar Docker y que los puertos, redes y recursos no entran en conflicto con otros servicios gestionados por Plesk.

Errores frecuentes al instalar Onyx con Docker

Los contenedores no terminan de estar disponibles

Consulta el estado y los registros:

onyx-cli deploy status
onyx-cli deploy logs

En una instalación manual utiliza:

docker compose ps
docker compose logs --tail=200

Las causas más habituales son memoria insuficiente, falta de espacio, permisos de Docker o un servicio dependiente que no ha terminado de iniciarse.

El puerto 3000 ya está ocupado

Comprueba qué proceso utiliza el puerto o modifica la asignación en la configuración de Compose. No cambies solamente el puerto de un contenedor sin revisar el proxy y las variables que dependen de él.

Onyx Lite no muestra conectores

No es un error. Lite desactiva los conectores, OpenSearch y la búsqueda RAG para reducir los recursos necesarios. Utiliza Standard si quieres sincronizar fuentes externas.

OpenSearch deja de aceptar escrituras

Comprueba el espacio disponible. Si el disco alcanzó el umbral crítico, primero libera o amplía almacenamiento. Después revisa la documentación de OpenSearch antes de retirar el bloqueo de solo lectura.

La interfaz abre, pero el chat no responde

Comprueba que hayas configurado un proveedor y un modelo válido desde el panel de administración. Revisa también el saldo, la API key y la conectividad con el proveedor.

El servidor se queda sin memoria

Comprueba que elegiste el modo adecuado. Para un servidor pequeño utiliza Lite. Standard necesita al menos 10 GB de RAM y puede requerir bastante más cuando aumenta la cantidad de documentos indexados.

Una actualización deja servicios incompatibles

Revisa las notas de la versión, las migraciones y los archivos de entorno. Si utilizaste el instalador guiado, administra la actualización mediante Onyx CLI en lugar de mezclarla con comandos manuales.

Instalar Onyx con Docker permite desplegar un entorno de inteligencia artificial conectado con los documentos y aplicaciones de una organización. Para probar el chat y los agentes, Onyx Lite ofrece una arquitectura sencilla y de bajo consumo. Para indexar fuentes externas y utilizar búsqueda RAG, debes elegir el despliegue Standard y reservar recursos suficientes.

La forma más sencilla de mantener la instalación es utilizar Onyx CLI, que administra la instalación, los registros, el estado y las actualizaciones. En producción también debes configurar autenticación, HTTPS, copias de seguridad y supervisión del almacenamiento.