Dify no arranca con Docker: errores y soluciones

Seguro que te ha pasado: quieres montar tu propia infraestructura de inteligencia artificial, instalas Dify y, de repente, el sistema no arranca o alguno de los contenedores de Docker entra en un ciclo de reinicios. Es un problema relativamente habitual cuando falta algún requisito, el archivo de configuración contiene un error o uno de los servicios dependientes no consigue iniciarse.

Dify permite crear flujos de trabajo, agentes y chatbots mediante una interfaz visual. Sin embargo, su instalación autohospedada depende de varios componentes, como PostgreSQL, Redis, Nginx, Weaviate y diferentes servicios internos. Por eso, cuando algo falla, la solución consiste en localizar exactamente qué contenedor está causando el problema en lugar de reiniciar Docker repetidamente sin revisar los registros.

Requisitos para que Dify funcione correctamente

Antes de buscar errores en los contenedores, comprueba que el equipo cumple los requisitos mínimos. La documentación oficial establece un mínimo de 2 núcleos de CPU y 4 GiB de memoria RAM. Aunque Dify puede arrancar con esos recursos, disponer de 8 GB ofrece más margen para procesar documentos y ejecutar varios servicios simultáneamente.

En Linux necesitas Docker Engine 19.03 o una versión posterior y Docker Compose 2.24.0 o superior. Puedes comprobar las versiones instaladas con estos comandos:

docker --version
docker compose version

Si utilizas Windows, Dify se ejecuta mediante Docker Desktop y WSL 2. Conviene almacenar el repositorio y los datos enlazados dentro del sistema de archivos de Linux, ya que trabajar desde una carpeta de Windows puede provocar problemas de rendimiento y permisos.

En Linux, tu usuario también debe disponer de permisos para ejecutar Docker. Puedes añadirlo al grupo correspondiente con:

sudo usermod -aG docker $USER

Después tendrás que cerrar la sesión y volver a entrar para que el cambio se aplique. Si no quieres modificar los grupos del sistema, también puedes ejecutar los comandos de Docker mediante sudo.

Descargar una versión estable y preparar el archivo .env

Para evitar instalar accidentalmente una versión de desarrollo, la documentación recomienda clonar la última release publicada. Puedes hacerlo con el siguiente comando:

git clone --branch "$(curl -s https://api.github.com/repos/langgenius/dify/releases/latest | jq -r .tag_name)" https://github.com/langgenius/dify.git

Este método requiere tener instalados Git, Curl y JQ. Después, entra en la carpeta de Docker y crea el archivo de configuración:

cd dify/docker
cp .env.example .env

El archivo .env contiene las variables utilizadas por los diferentes servicios. Si falta, está vacío o incluye valores incompatibles con la versión instalada, los contenedores pueden no arrancar o quedar marcados como no saludables.

Una vez preparado el archivo, inicia el despliegue:

docker compose up -d

Las versiones actuales levantan 7 servicios principales, 8 componentes dependientes y una tarea temporal llamada init_permissions. Esta última corrige los permisos del almacenamiento y después termina, por lo que verla con el estado Exited es completamente normal.

Cómo saber qué contenedor impide arrancar Dify

El primer paso para diagnosticar el problema es consultar el estado del despliegue:

docker compose ps

Los servicios deberían aparecer como Up o healthy. Si alguno figura como Restarting, unhealthy o Exited, ya tendrás una pista sobre el origen del error.

Para consultar los últimos mensajes de todos los servicios, utiliza:

docker compose logs --tail=100

También puedes limitar la salida al contenedor que está fallando:

docker compose logs --tail=100 nombre-del-servicio

Por ejemplo, si el problema se encuentra en PostgreSQL, ejecuta:

docker compose logs --tail=100 db_postgres

Si necesitas observar los mensajes mientras Docker intenta reiniciar el servicio, añade la opción -f:

docker compose logs -f nombre-del-servicio

Los registros suelen revelar si el fallo está relacionado con una contraseña incorrecta, una variable ausente, un puerto ocupado, falta de memoria, problemas de permisos o un volumen incompatible.

Errores habituales cuando Dify no arranca

Uno de los fallos más frecuentes consiste en clonar la rama principal del repositorio y conservar archivos de una instalación anterior. La rama main puede contener cambios que todavía no forman parte de una versión estable, mientras que un archivo .env antiguo puede no incluir las variables incorporadas recientemente.

Otro problema habitual es abrir Docker Desktop y esperar que la aplicación arranque automáticamente. Docker Desktop proporciona el motor y la interfaz para gestionar los contenedores, pero todavía necesitas preparar el archivo .env y ejecutar docker compose up -d desde la carpeta dify/docker.

Si Nginx no arranca, comprueba que los puertos 80 y 443 no estén siendo utilizados por otro servidor web:

docker compose logs --tail=100 nginx

En Linux también puedes consultar los procesos que utilizan esos puertos:

sudo ss -ltnp | grep -E ':80|:443'

Si el conflicto es intencionado, puedes modificar en .env las variables que controlan los puertos publicados:

EXPOSE_NGINX_PORT=8080
EXPOSE_NGINX_SSL_PORT=8443

Después de guardar los cambios, vuelve a crear los contenedores:

docker compose down
docker compose up -d

Cuando falla ssrf_proxy, revisa sus registros antes de cambiar archivos. El error puede proceder de la configuración de Squid, de un volumen montado incorrectamente o de problemas para resolver nombres de dominio desde la red de Docker.

Problemas de permisos y volúmenes

El servicio init_permissions está diseñado para asignar al almacenamiento los permisos que necesita la API. Si termina con el código cero, su estado Exited no indica un error.

Si muestra un fallo, consulta sus registros:

docker compose logs init_permissions

Los problemas pueden aparecer cuando la carpeta del proyecto se encuentra en un sistema de archivos que no gestiona correctamente los permisos de Linux, algo especialmente relevante en instalaciones de Windows con WSL 2.

No borres directamente el directorio volumes para intentar solucionar el problema. En él se almacenan datos persistentes de Dify, como la base de datos, los documentos y otros archivos necesarios para recuperar la instalación.

Antes de modificarlo, crea una copia de seguridad:

cp -a volumes volumes_backup

Si solo estás realizando una instalación nueva y todavía no has creado aplicaciones ni añadido información, puedes empezar de nuevo en otra carpeta limpia. En una instancia que ya contiene datos, conviene identificar el volumen problemático y revisar el error concreto antes de eliminar nada.

Qué hacer si Dify sigue sin arrancar

Si los contenedores continúan fallando, detén el despliegue y descarga nuevamente las imágenes:

docker compose down
docker compose pull
docker compose up -d

Después, comprueba otra vez el estado y los registros:

docker compose ps
docker compose logs --tail=100

También conviene comparar tu archivo .env con el nuevo .env.example. Las actualizaciones pueden añadir variables o modificar valores predeterminados, por lo que reutilizar una configuración antigua sin revisarla puede impedir que algunos servicios funcionen correctamente.

Cuando todos los contenedores estén activos, abre la página de instalación:

http://localhost/install

Si Dify se encuentra en otro equipo o servidor, sustituye localhost por su dirección IP. La primera carga puede tardar unos instantes mientras PostgreSQL, los workers y el resto de los servicios terminan de inicializarse.

Si la página continúa sin responder, comprueba que Nginx está activo, que el puerto publicado es el correcto y que ningún firewall está bloqueando la conexión.

La clave para solucionar que Dify no arranque consiste en examinar el estado y los registros de cada contenedor. Cumplir los requisitos, instalar una release estable, preparar correctamente el archivo .env y conservar los volúmenes permite resolver la mayoría de los problemas sin perder los proyectos almacenados.