Cómo instalar LibreChat con Docker: Guía completa

LibreChat permite montar una interfaz de inteligencia artificial parecida a ChatGPT dentro de un ordenador o servidor propio. Desde un único lugar puedes trabajar con proveedores comerciales, endpoints compatibles con OpenAI, modelos ejecutados mediante Ollama y servidores MCP.

Una de las formas más sencillas de instalarlo es utilizar Docker. Este sistema crea contenedores separados para LibreChat y sus servicios auxiliares, evitando tener que configurar manualmente MongoDB, Meilisearch y otras dependencias.

Sin embargo, la instalación cambia ligeramente dependiendo de si vas a ejecutar LibreChat en tu ordenador o en un servidor remoto con Ubuntu. También es importante entender para qué sirven los archivos .env, librechat.yaml y docker-compose.override.yml. A continuación veremos cómo instalar LibreChat con Docker y dejar preparada una configuración que pueda actualizarse sin perder los cambios.

Requisitos para instalar LibreChat con Docker

Para una instalación local necesitas dos herramientas:

• Git, utilizado para descargar el repositorio y recibir sus actualizaciones.
• Docker, encargado de ejecutar LibreChat y los servicios de los que depende.

En Windows y macOS, la opción más sencilla es instalar Docker Desktop. En Linux puede utilizarse Docker Engine junto con el plugin oficial de Docker Compose.

Puedes comprobar que ambas herramientas están disponibles con estos comandos:

git --version
docker --version
docker compose version

La última orden debe mostrar una versión de Compose. Actualmente se utiliza docker compose, sin guion, porque Compose v2 funciona como un plugin de Docker.

Para la instalación local no es necesario instalar Node.js ni NPM. Estas herramientas sí pueden resultar necesarias al utilizar determinados scripts incluidos en la guía de despliegue remoto de LibreChat.

Instalar Docker en un servidor Ubuntu

Si vas a alojar LibreChat en un VPS o servidor Ubuntu, conviene instalar Docker desde su repositorio oficial. De esta manera recibirás Docker Engine, la interfaz de línea de comandos y el plugin de Compose mantenidos por el propio proyecto.

Antes de empezar, actualiza el índice de paquetes:

sudo apt update
sudo apt upgrade

Después instala Git y sigue el procedimiento oficial de Docker para añadir su repositorio y sus paquetes. Una vez finalizada la instalación, comprueba que el servicio está funcionando:

sudo systemctl status docker

También puedes ejecutar:

sudo docker run hello-world

Si quieres utilizar Docker sin escribir sudo en cada orden, añade tu usuario al grupo correspondiente:

sudo usermod -aG docker $USER

Después debes cerrar la sesión y volver a entrar, o reiniciar el servidor. Ten en cuenta que los miembros del grupo docker disponen de un nivel de acceso muy elevado sobre el sistema. No añadas usuarios que no sean de confianza.

Instalar LibreChat en un ordenador

Para descargar LibreChat, abre una terminal y clona su repositorio oficial:

git clone https://github.com/danny-avila/LibreChat.git
cd LibreChat

El siguiente paso consiste en crear el archivo de variables de entorno a partir del ejemplo incluido en el proyecto:

cp .env.example .env

En Windows PowerShell, si el comando anterior no está disponible, utiliza:

Copy-Item .env.example .env

La configuración predeterminada permite realizar un primer arranque, aunque deberás revisar el archivo antes de utilizar LibreChat en un servidor accesible desde Internet.

Para iniciar los contenedores ejecuta:

docker compose up -d

Docker descargará las imágenes necesarias y creará los servicios. La primera puesta en marcha puede tardar varios minutos.

Cuando termine, abre en el navegador:

http://localhost:3080

LibreChat no incluye una contraseña predeterminada. La primera cuenta que registres se convertirá en la cuenta administradora, por lo que conviene crearla antes de permitir que otras personas accedan a la instancia.

Entender los archivos de configuración de LibreChat

LibreChat utiliza varios archivos con funciones diferentes:

• .env almacena claves de API, secretos, opciones de autenticación y variables del servidor.
• librechat.yaml define endpoints personalizados, modelos, servidores MCP y otros ajustes avanzados.
• docker-compose.yml contiene la definición principal de los servicios de Docker.
• docker-compose.override.yml permite añadir puertos, volúmenes y cambios propios sin modificar el archivo principal.

No es obligatorio crear librechat.yaml para que LibreChat arranque. Solo lo necesitas cuando quieras utilizar endpoints personalizados o determinadas funciones avanzadas.

Puedes generarlo a partir del ejemplo incluido:

cp librechat.example.yaml librechat.yaml

Las claves privadas no deberían escribirse directamente dentro del YAML. Es preferible guardarlas en .env y referenciarlas mediante variables.

Montar librechat.yaml dentro del contenedor

Cuando LibreChat se ejecuta mediante Docker, guardar librechat.yaml en el directorio del proyecto no siempre es suficiente. El contenedor de la API debe tener acceso al archivo.

Copia primero el archivo de anulación incluido como ejemplo:

cp docker-compose.override.yml.example docker-compose.override.yml

Después comprueba que contiene este volumen:

services:
  api:
    volumes:
      - type: bind
        source: ./librechat.yaml
        target: /app/librechat.yaml

Docker Compose combina automáticamente este archivo con docker-compose.yml. Así puedes conservar tus personalizaciones cuando actualices el repositorio.

Para aplicar los cambios, recrea los servicios:

docker compose down
docker compose up -d

Si el endpoint configurado no aparece en LibreChat, revisa los registros de la API:

docker compose logs api

Los fallos suelen deberse a una indentación incorrecta en el YAML, una variable ausente en .env o un volumen que no se ha montado correctamente.

Instalar LibreChat en un servidor remoto

LibreChat ofrece un archivo específico para servidores Linux con recursos limitados:

deploy-compose.yml

Este despliegue utiliza imágenes previamente compiladas, evitando que el servidor tenga que construir localmente la aplicación. También incorpora un contenedor NGINX que recibe las conexiones web.

Una vez descargado el repositorio y preparado el archivo .env, puedes iniciar la versión de despliegue con:

docker compose -f ./deploy-compose.yml up -d

Después podrás acceder desde:

http://IP_DEL_SERVIDOR

La dirección es diferente de la instalación local porque el archivo de despliegue publica NGINX en los puertos web habituales.

Antes de exponer la instancia, genera secretos únicos para las variables que lo requieran. Por ejemplo, el secreto de sesión del panel de administración puede generarse con:

openssl rand -hex 32

Copia el resultado en la variable correspondiente de .env sin compartirlo ni publicarlo en un repositorio.

Después de crear la cuenta administradora, también puedes desactivar el registro de nuevos usuarios:

ALLOW_REGISTRATION=false

Reinicia los servicios para aplicar cualquier modificación de las variables de entorno.

Configurar un dominio y proteger LibreChat con HTTPS

Editar únicamente el nombre del servidor en NGINX no basta para proteger una instalación. Primero debes crear un registro DNS que apunte el dominio hacia la dirección IP del servidor.

Después necesitarás un certificado TLS, por ejemplo mediante Let’s Encrypt, y configurar NGINX para utilizarlo. Si ejecutas el NGINX incluido en deploy-compose.yml, también tendrás que montar dentro del contenedor los archivos del certificado.

En client/nginx.conf, la directiva básica cambia de:

server_name localhost;

a:

server_name chat.ejemplo.com;

Además, debes configurar correctamente las variables de dominio de LibreChat en .env y seguir el procedimiento de certificados correspondiente a tu arquitectura.

No publiques una instancia con cuentas de usuario a través de HTTP. Cuando LibreChat sea accesible desde Internet, utiliza HTTPS, contraseñas robustas, un firewall y copias de seguridad de los volúmenes persistentes.

Cambiar el puerto 3080 de LibreChat

Si otra aplicación está utilizando el puerto 3080, Docker mostrará un error parecido a bind: address already in use.

No es necesario modificar el archivo principal. Añade esta configuración a docker-compose.override.yml:

services:
  api:
    ports:
      - "3081:3080"

Recrea los contenedores:

docker compose down
docker compose up -d

A partir de ese momento podrás abrir LibreChat mediante:

http://localhost:3081

Este ejemplo corresponde al Compose local. Si utilizas deploy-compose.yml, debes tener en cuenta que las conexiones pasan por el contenedor de NGINX.

Qué hacer si los contenedores se cierran

Para conocer el estado de los servicios ejecuta:

docker compose ps

Después consulta los registros del contenedor de la API:

docker compose logs api

También puedes seguir los mensajes en tiempo real:

docker compose logs -f api

Las causas más frecuentes son:

• El archivo .env no está en el directorio raíz del proyecto.
• librechat.yaml contiene un error de sintaxis o indentación.
• Falta una variable obligatoria.
• Docker no está iniciado.
• Un puerto necesario está siendo utilizado por otro programa.
• El servidor se ha quedado sin memoria durante el arranque.

Para comprobar si una variable ha llegado al contenedor puedes utilizar:

docker compose exec api env | grep -i NOMBRE_DE_LA_VARIABLE

No muestres el resultado completo de esta orden en capturas públicas, ya que el entorno puede contener credenciales.

Cómo actualizar LibreChat instalado con Docker

En la instalación local, la documentación de LibreChat recomienda detener los servicios, descargar los cambios del repositorio y obtener las imágenes actualizadas:

docker compose down
git pull
docker compose pull
docker compose up -d

Si utilizas el despliegue remoto y tienes disponibles los scripts del proyecto, puedes ejecutar:

npm run update:deployed

También es posible hacerlo manualmente:

docker compose -f ./deploy-compose.yml down
git pull
docker compose -f ./deploy-compose.yml pull
docker compose -f ./deploy-compose.yml up -d

Si has modificado directamente archivos controlados por Git, la actualización puede generar conflictos. Por eso conviene guardar las personalizaciones en .env, librechat.yaml y archivos de anulación siempre que sea posible.

La configuración remota predeterminada puede seguir la imagen compilada desde la rama principal. Si priorizas la estabilidad, revisa las etiquetas publicadas por LibreChat y configura expresamente una versión estable, teniendo en cuenta que dejarás de recibir inmediatamente las funciones recién incorporadas.

Instalar LibreChat con Docker permite reunir modelos locales y proveedores externos en una misma interfaz sin llenar el sistema de dependencias. La clave está en escoger el archivo de Compose adecuado, separar correctamente los secretos y la configuración, proteger el acceso remoto y conservar las personalizaciones fuera de los archivos principales del proyecto.

Con la instancia en funcionamiento, el siguiente paso puede ser añadir Ollama, OpenRouter, un proveedor comercial o conectar servidores MCP con LibreChat.