Stacks y Docker Compose

Un stack es una aplicación multi-contenedor definida con la sintaxis de Docker Compose. Es la forma recomendada de desplegar en Portainer: declarativo, reproducible y versionable. Si venís de docker compose up, los stacks te van a resultar familiares.

Qué es un stack en Portainer

Portainer toma un archivo compose.yaml y lo despliega como un conjunto de servicios, redes y volúmenes relacionados. En Docker standalone usa Compose por detrás; en Swarm, despliega como docker stack deploy. La sección Stacks los lista y te deja crearlos, editarlos y removerlos como una unidad.

flowchart LR
    A["Editor web<br/>(pegás Compose)"] --> D["Stack desplegado"]
    B["Upload<br/>(.yml)"] --> D
    C["Repositorio Git<br/>(ruta al compose)"] --> D
    D --> S1["servicio web"]
    D --> S2["servicio db"]
    D --> V["volumen"]
    D --> N["red"]

Crear un stack desde el editor web

Stacks → + Add stack → Web editor. Le das un nombre y pegás tu Compose. Ejemplo de una app web con su base de datos:

services:
  web:
    image: nginx:alpine
    ports:
      - "8080:80"
    networks:
      - frontend
    restart: unless-stopped

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - db_data:/var/lib/postgresql/data
    networks:
      - frontend

networks:
  frontend:

volumes:
  db_data:

Al Deploy the stack, Portainer crea los dos servicios, la red frontend (donde web resuelve a db por nombre) y el volumen db_data.

Variables de entorno

Fijate en ${DB_PASSWORD} arriba. Debajo del editor, Portainer ofrece una sección de Environment variables donde definís esos valores. Ventajas:

• No hardcodeás secretos en el YAML.
• Reutilizás el mismo Compose en distintos entornos cambiando solo las variables.

Para secretos de verdad en Swarm, usá Docker secrets (capítulo 9) en vez de variables de entorno.

Desplegar desde un repositorio Git

La opción más poderosa: Stacks → + Add stack → Repository. Indicás:

• URL del repo y rama.
• Ruta al Compose dentro del repo (ej. deploy/compose.yaml).
• Credenciales si el repo es privado.
• Opcionalmente, auto-update por polling (Portainer revisa el repo cada N minutos) o por webhook (el repo avisa a Portainer al hacer push).

Esto convierte a Portainer en un mini-motor de GitOps: tu definición vive en Git, y Portainer mantiene el entorno sincronizado. Lo profundizamos en el capítulo 13.

Editar y actualizar un stack

Desde el detalle del stack:

• Editor: cambiás el Compose y redeployás; Portainer reconcilia (recrea solo lo que cambió).
• Re-pull and redeploy: vuelve a bajar las imágenes y recrea, para actualizar a las versiones nuevas.
• Si el stack viene de Git, el editor te muestra que está gestionado por Git y el redeploy se hace desde el repo.

Stacks vs contenedores sueltos

	Contenedor suelto	Stack
Definición	Formulario / docker run	Archivo Compose versionable
Multi-servicio	Manual, uno por uno	Declarativo, todo junto
Reproducible	No	Sí
GitOps	No	Sí

Regla: si tu app tiene más de un contenedor, o querés poder recrearla en otro host idéntica, usá un stack.

Control de acceso del stack

Al crear un stack podés definir a qué usuarios/equipos pertenece (administración de acceso). Combinado con el RBAC del capítulo 12, esto permite que un equipo gestione sus stacks sin ver los de otros.

---

Anterior → Capítulo 5: Imágenes, volúmenes y redes · Siguiente → Capítulo 7: App Templates