Guía Completa sobre Creación y Gestión de Stacks en Docker

Una vez instalado Dockge, puedes utilizar su panel para desplegar aplicaciones formadas por uno o varios contenedores sin escribir continuamente comandos en la terminal. Cada aplicación se administra como un stack de Docker Compose, con sus servicios, variables, redes y volúmenes reunidos en un mismo proyecto.

Esto resulta especialmente útil cuando una aplicación necesita varios componentes trabajando conjuntamente. Por ejemplo, un servicio como Gitea puede requerir un contenedor para la aplicación y otro para PostgreSQL. Dockge permite editar la configuración, iniciar el conjunto, revisar sus registros y actualizar las imágenes desde una sola interfaz.

Esta guía parte de que Docker y Dockge ya están funcionando. Si todavía no has preparado el panel, primero debes instalar Dockge con Docker Compose y configurar correctamente su carpeta de stacks.

Qué considera Dockge un stack

En Dockge, un stack es esencialmente un proyecto de Docker Compose. Normalmente está formado por una carpeta que contiene un archivo compose.yaml y, opcionalmente, un archivo .env, configuraciones adicionales, certificados o directorios utilizados como volúmenes.

Con la configuración predeterminada, Dockge guarda los proyectos siguiendo esta estructura:

/opt/stacks/
├── gitea/
│   ├── compose.yaml
│   └── .env
├── stirling-pdf/
│   └── compose.yaml
└── vaultwarden/
    ├── compose.yaml
    └── .env

Cada subcarpeta representa un stack independiente. Esta estructura basada en archivos permite administrar los mismos proyectos desde Dockge o mediante comandos tradicionales como docker compose up, docker compose down y docker compose logs.

No debe confundirse este concepto con los stacks de Docker Swarm. Dockge utiliza Docker Compose y no convierte el servidor en un clúster. Elementos como los nodos manager y worker, el Routing Mesh, los servicios globales o el comando docker stack deploy pertenecen a Swarm y no intervienen en este procedimiento.

Aunque Dockge puede conectarse a distintos hosts mediante agentes, cada stack continúa ejecutándose como un proyecto Compose en el host correspondiente.

Qué necesitas antes de crear el stack

Antes de desplegar una aplicación, conviene reunir los datos que necesitará su archivo Compose:

• La imagen oficial de cada servicio y la etiqueta que quieres utilizar.
• Los puertos del anfitrión que estarán disponibles.
• Las carpetas o volúmenes donde se conservarán los datos.
• Las variables de entorno requeridas por la aplicación.
• Las credenciales de la base de datos y otros servicios internos.
• Los permisos necesarios para acceder a los directorios montados.

También debes decidir qué servicios necesitan exposición externa. Una base de datos utilizada solamente por otra aplicación del stack no necesita publicar su puerto en el anfitrión. Los contenedores pueden comunicarse directamente a través de la red interna creada por Compose.

Para practicar con una aplicación de un solo servicio antes de crear proyectos más complejos, puedes instalar Stirling PDF con Docker y administrarlo posteriormente desde Dockge.

Cómo crear un nuevo stack en Dockge

Accede al panel de Dockge y pulsa el control para crear un nuevo stack. Introduce un nombre breve y reconocible, preferiblemente compuesto por letras minúsculas, números y guiones, sin espacios ni caracteres especiales.

Por ejemplo:

gitea

Dockge creará una carpeta para el proyecto dentro del directorio configurado para los stacks. En el editor principal puedes escribir o pegar el contenido de compose.yaml.

El siguiente ejemplo crea un servidor de Gitea acompañado por una base de datos PostgreSQL:

services:
  db:
    image: postgres:17-alpine
    restart: unless-stopped
    environment:
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - db_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $$POSTGRES_USER -d $$POSTGRES_DB"]
      interval: 10s
      timeout: 5s
      retries: 5

  gitea:
    image: docker.gitea.com/gitea:1-rootless
    restart: unless-stopped
    environment:
      GITEA__database__DB_TYPE: postgres
      GITEA__database__HOST: db:5432
      GITEA__database__NAME: ${POSTGRES_DB}
      GITEA__database__USER: ${POSTGRES_USER}
      GITEA__database__PASSWD: ${POSTGRES_PASSWORD}
    ports:
      - "${GITEA_HTTP_PORT:-3000}:3000"
      - "${GITEA_SSH_PORT:-2222}:2222"
    volumes:
      - gitea_data:/var/lib/gitea
      - gitea_config:/etc/gitea
    depends_on:
      db:
        condition: service_healthy

volumes:
  db_data:
  gitea_data:
  gitea_config:

Las versiones actuales de Docker Compose siguen la Compose Specification. Por tanto, ya no es necesario comenzar el archivo con propiedades como version: "3". Compose utiliza automáticamente el esquema más reciente que reconoce.

Cómo configurar las variables de entorno

El ejemplo anterior utiliza referencias como ${POSTGRES_PASSWORD}. Estos valores deben definirse en un archivo .env situado en la carpeta del mismo stack.

Para el ejemplo de Gitea, el contenido podría ser:

POSTGRES_DB=gitea
POSTGRES_USER=gitea
POSTGRES_PASSWORD=CAMBIA_ESTA_CONTRASENA
GITEA_HTTP_PORT=3000
GITEA_SSH_PORT=2222

Sustituye la contraseña de ejemplo por una credencial larga y aleatoria. El archivo .env facilita la reutilización del Compose, pero no cifra los secretos. Debes limitar sus permisos, excluirlo de repositorios Git y evitar compartirlo junto con capturas o copias públicas del proyecto.

Para entornos más exigentes, Docker Compose admite secretos montados como archivos dentro de los contenedores. Tanto PostgreSQL como Gitea permiten leer la contraseña desde un archivo, evitando que aparezca directamente entre las variables del servicio.

Dockge dispone de acceso al socket de Docker para administrar los contenedores. Por este motivo, solamente los administradores de confianza deberían acceder al panel. Tampoco debes pegar configuraciones Compose de procedencia desconocida: podrían montar carpetas sensibles del anfitrión o solicitar privilegios elevados.

Cómo funcionan las redes y los nombres de servicio

Docker Compose crea automáticamente una red predeterminada para cada proyecto. Todos los servicios conectados a ella pueden localizarse mediante el nombre utilizado en compose.yaml.

En el ejemplo, Gitea se conecta a PostgreSQL mediante:

db:5432

db es el nombre del servicio, no una dirección IP fija. Docker mantiene esta resolución interna aunque el contenedor sea recreado y reciba una dirección diferente.

No debes utilizar localhost para comunicar dos contenedores. Dentro del contenedor de Gitea, localhost hace referencia al propio Gitea, no al contenedor de PostgreSQL.

Tampoco es necesario publicar el puerto 5432 de la base de datos si solamente Gitea necesita conectarse a ella. Al no exponerlo en la sección ports, reduces la superficie de ataque del servidor.

Cómo conservar los datos del stack

Los contenedores son reemplazables. Si guardas información únicamente dentro de su sistema de archivos interno, puedes perderla al recrearlos. Para evitarlo, el ejemplo declara tres volúmenes persistentes:

• db_data conserva la base de datos PostgreSQL.
• gitea_data guarda los repositorios y datos de Gitea.
• gitea_config conserva la configuración de la aplicación.

Detener o recrear el stack no elimina automáticamente estos volúmenes. Sin embargo, siguen residiendo en el mismo servidor, por lo que no sustituyen a una copia de seguridad.

También puedes utilizar bind mounts para guardar los archivos en rutas concretas del anfitrión. En ese caso, comprueba que las carpetas existan y que el usuario utilizado por el contenedor tenga permisos suficientes para leerlas o escribir en ellas.

Por qué utilizar healthchecks y depends_on

La propiedad depends_on establece el orden en el que Compose crea los servicios, pero iniciar un contenedor no significa que la aplicación alojada en él esté preparada.

PostgreSQL puede necesitar varios segundos para inicializar la base de datos. Si Gitea intenta conectarse demasiado pronto, puede mostrar errores aunque ambos contenedores estén en ejecución.

El healthcheck del ejemplo ejecuta periódicamente pg_isready. La condición service_healthy hace que Compose espere hasta que PostgreSQL responda correctamente antes de iniciar Gitea. Esta combinación resulta especialmente útil en stacks que incluyen bases de datos, colas o servicios de almacenamiento.

Cómo iniciar y comprobar el stack

Después de completar el archivo Compose y las variables, guarda los cambios e inicia el stack desde Dockge. El panel mostrará en tiempo real la descarga de imágenes, la creación de volúmenes y el arranque de los contenedores.

Comprueba que PostgreSQL aparezca como saludable y que Gitea permanezca en ejecución. Después abre:

http://IP_DEL_SERVIDOR:3000

Desde la terminal también puedes verificar el proyecto:

cd /opt/stacks/gitea
docker compose config
docker compose ps
docker compose logs --tail=100

docker compose config muestra la configuración final después de resolver las variables. Resulta especialmente útil para localizar errores de sintaxis, valores vacíos o sustituciones inesperadas antes de iniciar los servicios.

Cuando necesites renovar las imágenes, puedes actualizar un contenedor Docker usando Dockge. Antes de una actualización importante, realiza una copia de seguridad de los volúmenes y revisa los cambios de la versión.

Cómo importar un stack existente en Dockge

Dockge también puede administrar proyectos Compose creados anteriormente desde la terminal. El procedimiento recomendado es:

1. Detener el proyecto existente para evitar duplicados.
2. Crear una subcarpeta dentro del directorio de stacks.
3. Mover allí el archivo con el nombre compose.yaml.
4. Copiar también su archivo .env y los archivos auxiliares.
5. Utilizar la opción Scan Stacks Folder de Dockge.
6. Revisar la configuración antes de volver a iniciar el proyecto.

Por ejemplo:

/opt/stacks/mi-aplicacion/compose.yaml

Si configuraste una carpeta diferente a /opt/stacks, recuerda que la ruta montada dentro del contenedor de Dockge debe ser idéntica a la ruta absoluta del anfitrión. Las rutas diferentes pueden provocar que los bind mounts relativos apunten a ubicaciones equivocadas.

Errores frecuentes al crear un stack en Dockge

El archivo YAML no es válido

YAML depende de la sangría y no admite tabulaciones en lugar de espacios. Revisa especialmente las secciones services, volumes y environment. Ejecuta docker compose config para localizar la línea problemática.

Aparece el error port is already allocated

Otro contenedor o servicio está utilizando el mismo puerto del anfitrión. Cambia solamente el valor situado a la izquierda de la asignación. Por ejemplo, sustituye 3000:3000 por 3001:3000.

Las variables aparecen vacías

Comprueba que el archivo se llame exactamente .env, que esté dentro de la carpeta del stack y que los nombres coincidan con los utilizados en compose.yaml. Revisa el resultado de docker compose config sin compartir su salida si contiene secretos.

La aplicación no encuentra la base de datos

Utiliza el nombre del servicio como hostname. En el ejemplo debe emplearse db, no localhost ni una dirección IP asignada manualmente. Comprueba también que ambos servicios compartan una red.

La aplicación arranca antes que PostgreSQL

depends_on sin una comprobación de salud solamente controla el orden de creación. Añade un healthcheck a la base de datos y utiliza la condición service_healthy.

Aparece permission denied al montar una carpeta

Verifica que la ruta exista en el anfitrión, que sea absoluta cuando corresponda y que sus permisos permitan el acceso del usuario interno del contenedor. No concedas permisos globales de escritura como solución permanente.

El stack no aparece en Dockge

Comprueba que el archivo se encuentre directamente en una estructura como /opt/stacks/nombre/compose.yaml. Después ejecuta Scan Stacks Folder. Los proyectos guardados fuera de la carpeta configurada no aparecerán automáticamente.

El contenedor entra continuamente en estado restarting

Abre los registros desde Dockge o ejecuta docker compose logs. Las causas más habituales son credenciales incorrectas, variables obligatorias ausentes, permisos insuficientes o una dependencia que todavía no está disponible.

Crear un stack en Dockge consiste en definir una aplicación mediante Docker Compose, guardar sus variables y datos persistentes y desplegarla desde una interfaz visual. La clave está en utilizar nombres de servicio para la comunicación interna, exponer solamente los puertos necesarios y comprobar la disponibilidad de las dependencias mediante healthchecks.

Dockge simplifica la administración, pero los proyectos siguen siendo archivos Compose normales. Esto permite conservar el control sobre la configuración, utilizar la línea de comandos cuando sea necesario y migrar los stacks a otro servidor sin depender de una base de datos propietaria.