Cómo instalar Dockge con Docker Compose paso a paso

Administrar varios servicios mediante archivos de Docker Compose puede terminar convirtiéndose en una sucesión interminable de comandos, carpetas y terminales abiertas. Dockge simplifica esta gestión mediante una interfaz web desde la que puedes crear, editar, iniciar, detener y actualizar stacks sin abandonar los archivos compose.yaml tradicionales.

A diferencia de un panel generalista para Docker, Dockge está diseñado específicamente alrededor de Docker Compose y sus stacks. Los archivos permanecen almacenados en el servidor y pueden seguir utilizándose desde la terminal, por lo que no quedas atrapado en un formato propietario ni pierdes el control sobre la configuración.

En esta guía aprenderás a instalar Dockge con Docker Compose, configurar correctamente la carpeta de stacks, importar servicios existentes y proteger un panel que dispone de acceso administrativo al motor de Docker.

Qué es Dockge y cuándo merece la pena utilizarlo

Dockge es una aplicación autoalojada que proporciona una interfaz gráfica para gestionar stacks de Docker Compose. Permite editar el archivo YAML, consultar la salida de los comandos y controlar los servicios desde el navegador.

Entre sus funciones principales se encuentran:

• Crear y editar stacks basados en archivos compose.yaml.
• Iniciar, detener, reiniciar y eliminar servicios.
• Descargar versiones nuevas de las imágenes utilizadas.
• Consultar en tiempo real la salida de pull, up y down.
• Convertir determinados comandos docker run en configuraciones de Compose.
• Gestionar varios hosts mediante agentes compatibles.
• Continuar utilizando los archivos mediante los comandos normales de Docker Compose.

Dockge no pretende administrar todas las funciones de Docker. Su objetivo son los proyectos organizados como stacks de Compose. Si necesitas gestionar contenedores aislados, redes, volúmenes y otros recursos desde un único panel, conviene comparar previamente Dockge frente a Portainer.

Requisitos para instalar Dockge

Antes de comenzar, necesitas un servidor compatible con los requisitos oficiales:

• Una distribución Linux compatible, como Ubuntu, Debian, Raspberry Pi OS, Fedora, CentOS o Arch Linux.
• Docker 20 o una versión posterior, o una instalación compatible de Podman.
• Docker Compose V2, disponible mediante el comando docker compose.
• Arquitectura AMD64, ARM64 o ARMv7.
• Acceso administrativo al servidor.
• El puerto TCP 5001 disponible o un puerto alternativo.

Dockge no admite Windows oficialmente. Aunque determinadas configuraciones podrían ejecutarse dentro de una máquina virtual o un entorno Linux, para un servidor estable conviene utilizar una distribución Linux compatible.

Comprueba Docker y Compose mediante:

docker --version
docker compose version

Si el segundo comando no funciona, tendrás que instalar el plugin Docker Compose V2 en Linux. No es recomendable recurrir a la antigua versión independiente que utiliza el comando docker-compose, ya que se mantiene únicamente por compatibilidad.

Si todavía no dispones del motor, sigue un procedimiento específico para instalar Docker Engine en Ubuntu Server o en la distribución que estés utilizando. No es necesario repetir aquí toda la instalación de Docker.

Cómo instalar Dockge con Docker Compose

La instalación oficial utiliza dos directorios. /opt/dockge almacena el archivo de composición y la configuración del panel, mientras que /opt/stacks contiene los stacks administrados.

Crea ambos directorios:

sudo mkdir -p /opt/dockge /opt/stacks
cd /opt/dockge

Descarga el archivo oficial:

sudo curl -fsSL https://raw.githubusercontent.com/louislam/dockge/master/compose.yaml --output compose.yaml

Antes de iniciar el contenedor, valida su sintaxis:

sudo docker compose config

Si no aparecen errores, despliega Dockge:

sudo docker compose up -d

Comprueba que el contenedor está activo:

sudo docker compose ps

También puedes revisar el arranque mediante:

sudo docker compose logs -f dockge

Si tu usuario pertenece al grupo docker, podrás ejecutar estos comandos sin sudo. Sin embargo, debes saber que pertenecer al grupo docker concede privilegios equivalentes a root sobre el servidor.

Cómo configurar el archivo compose.yaml de Dockge

El archivo oficial utiliza una configuración similar a la siguiente:

services:
  dockge:
    image: louislam/dockge:1
    restart: unless-stopped
    ports:
      - "5001:5001"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./data:/app/data
      - /opt/stacks:/opt/stacks
    environment:
      - DOCKGE_STACKS_DIR=/opt/stacks

Cada elemento cumple una función concreta:

• louislam/dockge:1 utiliza la rama estable principal de Dockge.
• 5001:5001 publica la interfaz web en el puerto 5001.
• ./data:/app/data conserva usuarios, preferencias y configuración del panel.
• /var/run/docker.sock permite que Dockge controle el motor de Docker.
• /opt/stacks almacena los proyectos administrados mediante Compose.

El montaje de docker.sock es imprescindible para el funcionamiento habitual, pero también proporciona al contenedor control administrativo sobre Docker y el servidor. No instales imágenes de Dockge procedentes de fuentes desconocidas.

Cómo configurar correctamente la carpeta de stacks

Dockge impone una condición que suele provocar errores: la ruta de la carpeta debe ser idéntica en el host, dentro del contenedor y en la variable DOCKGE_STACKS_DIR.

Esta configuración es correcta:

volumes:
  - /opt/stacks:/opt/stacks
environment:
  - DOCKGE_STACKS_DIR=/opt/stacks

En cambio, no debes montar /srv/docker/stacks como /opt/stacks. Si quieres utilizar una ruta personalizada, repítela en ambos lados:

volumes:
  - /srv/docker/stacks:/srv/docker/stacks
environment:
  - DOCKGE_STACKS_DIR=/srv/docker/stacks

Cada stack debe disponer de una carpeta propia:

/opt/stacks/
├── jellyfin/
│   ├── compose.yaml
│   └── .env
├── vaultwarden/
│   └── compose.yaml
└── authentik/
    ├── compose.yaml
    └── .env

Si quieres que los archivos creados desde Dockge pertenezcan a un usuario concreto, consulta su UID y GID:

id -u
id -g

Después puedes añadir ambos valores a la sección environment:

environment:
  - DOCKGE_STACKS_DIR=/opt/stacks
  - PUID=1000
  - PGID=1000

Sustituye 1000 por los identificadores obtenidos en tu servidor. Es necesario definir tanto PUID como PGID para que esta configuración tenga efecto.

Cómo acceder a Dockge y crear el administrador

Después de iniciar el contenedor, abre en el navegador:

http://IP_DEL_SERVIDOR:5001

Durante el primer acceso aparecerá el formulario para crear la cuenta administradora de Dockge. Utiliza una contraseña larga y exclusiva, porque esta cuenta puede editar configuraciones, leer variables de entorno y controlar todos los stacks visibles.

Si solo administras el servidor desde el propio equipo, también puedes acceder mediante:

http://localhost:5001

No desactives la autenticación para ahorrar este paso. La interfaz debe considerarse un panel administrativo de alta confianza.

Cómo importar stacks existentes en Dockge

Dockge puede detectar proyectos creados previamente con Docker Compose, pero sus archivos deben encontrarse dentro del directorio configurado para los stacks.

1. Accede a la carpeta donde se encuentra el proyecto existente.
2. Detén el stack mediante docker compose down.
3. Mueve su carpeta completa a /opt/stacks/NOMBRE_DEL_STACK/.
4. Comprueba que el archivo se llame compose.yaml, compose.yml, docker-compose.yaml o docker-compose.yml.
5. Abre el menú superior de Dockge.
6. Selecciona Scan Stacks Folder.

Conviene mover la carpeta completa y no solamente el archivo YAML. Un stack puede depender de un archivo .env, configuraciones adicionales o rutas relativas utilizadas por los volúmenes.

Los contenedores creados exclusivamente con docker run no aparecerán como stacks administrables hasta que dispongan de un archivo Compose compatible.

Cómo proteger el acceso a Dockge

Dockge no debe exponerse directamente a Internet. El panel controla Docker mediante su socket y una cuenta comprometida podría crear contenedores privilegiados, leer archivos de configuración o modificar otros servicios.

Advertencia de seguridad: en agosto de 2026 se publicó la vulnerabilidad CVE-2026-73040, relacionada con la validación de los nombres de los stacks. En el momento de esta revisión, el aviso todavía no especificaba una versión corregida. Hasta disponer de una actualización confirmada, limita el uso a administradores de confianza y no publiques el puerto 5001.

Para reducir el riesgo:

• No utilices ninguna opción que desactive la autenticación.
• Limita el puerto 5001 mediante el cortafuegos a una red administrativa.
• Utiliza una VPN para acceder al panel desde fuera de casa.
• Si necesitas un dominio, configura un proxy inverso con HTTPS.
• No compartas la cuenta administradora entre varias personas.
• Mantén desactivada la consola web si no la necesitas.
• Revisa los avisos de seguridad antes de actualizar o exponer el servicio.

La versión estable 1.5.0 mantiene la consola desactivada de forma predeterminada. No añadas DOCKGE_ENABLE_CONSOLE=true salvo que entiendas sus implicaciones y necesites expresamente esta función.

Cómo actualizar y hacer copias de seguridad de Dockge

Antes de actualizar, guarda una copia de estas ubicaciones:

• /opt/dockge/data, que contiene la configuración y los usuarios.
• /opt/stacks, donde residen los archivos Compose y sus variables.
• Los volúmenes o directorios persistentes utilizados por cada aplicación.

Copiar únicamente la carpeta data de Dockge no protege los stacks ni los datos de sus aplicaciones. Debes incluir ambas rutas en tu estrategia para hacer copias de seguridad de stacks Docker Compose.

Para descargar la imagen nueva y recrear el contenedor:

cd /opt/dockge
sudo docker compose pull
sudo docker compose up -d

Después comprueba el estado y los registros:

sudo docker compose ps
sudo docker compose logs --tail=100 dockge

Es preferible actualizar Dockge desde la terminal. Si intentas que Dockge actualice su propio contenedor desde el panel, la aplicación puede detener el proceso que debía volver a iniciarla.

Errores frecuentes al instalar Dockge

docker: ‘compose’ is not a docker command

Docker Compose V2 no está instalado. En Ubuntu o Debian con el repositorio oficial de Docker configurado, instala el plugin mediante:

sudo apt update
sudo apt install docker-compose-plugin

Comprueba después la instalación con docker compose version.

No configuration file provided

El comando se está ejecutando desde una carpeta que no contiene el archivo. Entra en /opt/dockge y confirma que existe compose.yaml:

cd /opt/dockge
ls -la
sudo docker compose up -d

La página no responde en el puerto 5001

Comprueba que el contenedor esté activo y que ningún cortafuegos bloquee el puerto:

sudo docker compose ps
sudo docker compose logs --tail=100 dockge
sudo ss -lntp | grep 5001

Si has cambiado el mapeo a 8080:5001, deberás entrar mediante el puerto 8080 del servidor.

Permission denied al acceder a docker.sock

Dockge no puede comunicarse con Docker. Verifica que el volumen /var/run/docker.sock:/var/run/docker.sock esté presente y que el demonio se encuentre activo.

No cambies los permisos del socket a 777. Ejecutar Docker mediante sudo o añadir un usuario al grupo docker son soluciones habituales, pero recuerda que dicho grupo concede privilegios administrativos equivalentes a root.

Los stacks no aparecen en la interfaz

Cada proyecto debe encontrarse en una subcarpeta directa del directorio de stacks y contener un archivo Compose reconocible. Después utiliza Scan Stacks Folder.

Una estructura como /opt/stacks/categoria/proyecto/compose.yaml puede no detectarse correctamente. Utiliza preferiblemente /opt/stacks/proyecto/compose.yaml.

Dockge escribe datos en una ruta incorrecta

La ruta izquierda y la derecha del volumen no coinciden. Utiliza siempre la misma ruta absoluta y repítela en DOCKGE_STACKS_DIR.

El stack aparece como no administrado

Detén el proyecto original, mueve su carpeta al directorio de stacks y vuelve a escanearlo. Dockge necesita tanto el archivo Compose como una estructura coherente para asociarlo con los contenedores existentes.

La interfaz funciona, pero se pierden usuarios o ajustes

Comprueba que el volumen ./data:/app/data siga presente. Si el contenedor se recrea sin este montaje persistente, la nueva instancia no encontrará la base de datos anterior.

Los registros resultan difíciles de consultar

Dockge muestra la salida de los comandos de cada stack, pero para centralizar y filtrar registros de muchos contenedores puede ser más práctico monitorizar los logs de Docker con Dozzle.

Instalar Dockge permite convertir una colección dispersa de archivos Compose en un panel visual centralizado sin renunciar al control desde la terminal. La parte más delicada no es iniciar el contenedor, sino configurar correctamente la carpeta de stacks y proteger una interfaz que dispone de acceso directo al motor de Docker.

Si mantienes el panel dentro de una red administrativa, conservas copias de /opt/stacks y revisas los avisos de seguridad antes de actualizar, Dockge puede resultar especialmente cómodo para administrar un laboratorio doméstico o un servidor con numerosos servicios autoalojados.