Documentación / Conceptos fundamentales / Stacks

Stacks

Un stack es la unidad organizativa de nivel superior en sh0. Agrupa aplicaciones y servicios relacionados, proporcionando configuración compartida y una vista unificada de tu proyecto.

¿Qué es un stack?

Un stack representa un proyecto o producto que consta de una o más aplicaciones y servicios. Por ejemplo, un stack típico de aplicación web podría incluir:

Una aplicación frontend (React, Vue, Svelte)
Una API backend (Node.js, Python, Go)
Una base de datos PostgreSQL
Una caché Redis
Un worker en segundo plano

Todos estos viven dentro de un stack, comparten variables de entorno y pueden comunicarse a través de una red Docker privada. Cuando abres un stack en el panel de control, ves todos sus componentes de un vistazo.

Stack list view showing three stacks: 'production-api' with 4 services running, 'staging-frontend' with 2 services running, and 'blog' with 1 service running -- each showing status badges and resource usage

The stack list gives you an overview of all your projects

Stacks vs. aplicaciones vs. servicios

Es importante entender la jerarquía:

Concepto	Descripción	Ejemplo
Stack	Un agrupamiento de proyecto o producto	"E-commerce Platform"
Aplicación	Una unidad desplegable dentro de un stack	"api", "frontend", "worker"
Servicio	Una instancia de contenedor en ejecución de una aplicación	"api-v3-abc123" (container)

Un stack contiene una o más aplicaciones. Cada aplicación se ejecuta como uno o más servicios (contenedores). Cuando despliegas una aplicación, sh0 crea un nuevo servicio (contenedor) y opcionalmente elimina el anterior después de que la verificación de salud sea exitosa.

Note

Todas las aplicaciones dentro de un stack comparten una red Docker, lo que significa que pueden comunicarse entre sí usando el nombre de la aplicación como nombre de host. Por ejemplo, tu frontend puede acceder a la API en http://api:3000 sin ninguna configuración adicional.

Crear un stack

Hay dos formas de crear un stack:

Desde el panel de control:

Haz clic en Nuevo stack en la esquina superior derecha o desde la página de stacks.
Ingresa un nombre (solo minúsculas, alfanumérico y guiones).
Agrega una descripción opcional.
Haz clic en Crear stack.

Create Stack dialog with fields for name, description, and a Create Stack button

Creating a new stack from the dashboard

Desde la API:

Terminal

curl -X POST http://localhost:9000/api/projects \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-stack", "description": "Production web app"}'

Vista de detalle del stack

Al hacer clic en un stack se abre la vista de detalle, que proporciona una imagen completa de tu proyecto:

Stack detail view showing tabs for Apps, Environment, Domains, Backups, and Settings. The Apps tab is active, showing a grid of three apps: frontend (running), api (running), and database (running) with resource usage bars

The stack detail view with all apps visible

Pestaña de aplicaciones -- Todas las aplicaciones en este stack con su estado, uso de recursos y acciones rápidas (desplegar, reiniciar, detener).
Pestaña de entorno -- Variables de entorno a nivel de stack compartidas entre todas las aplicaciones.
Pestaña de dominios -- Todos los dominios asignados a las aplicaciones de este stack.
Pestaña de respaldos -- Programaciones de respaldo e historial para las bases de datos en este stack.
Pestaña de configuración -- Nombre del stack, descripción, zona de peligro (eliminar stack).

Variables de entorno del stack

Las variables de entorno a nivel de stack son heredadas por todas las aplicaciones del stack. Esto es útil para configuración compartida como claves de API, URLs de bases de datos o feature flags que aplican a todo el proyecto.

Example Stack Variables

DATABASE_URL=postgres://user:pass@db:5432/myapp
REDIS_URL=redis://cache:6379
APP_ENV=production
STRIPE_API_KEY=sk_live_...

Stack Environment tab showing a list of environment variables with name, value (masked), and action buttons. An 'Add Variable' button and 'Import .env' button are at the top

Managing stack-level environment variables

Precedencia de variables

Las variables de entorno a nivel de aplicación anulan las del nivel de stack. Si un stack define APP_ENV=production y una aplicación define APP_ENV=staging, la aplicación usa staging. Esto te permite compartir valores predeterminados mientras permites anulaciones por aplicación.

Configuración del stack

La pestaña de configuración te permite modificar los metadatos del stack y realizar acciones administrativas:

Nombre y descripción -- Actualiza el nombre y la descripción del stack.
Red Docker -- Consulta el nombre de la red Docker interna de este stack.
Zona de peligro -- Eliminar el stack y todas sus aplicaciones, servicios y datos. Esta acción es irreversible.

Eliminar un stack

Eliminar un stack remueve todas las aplicaciones, contenedores, volúmenes y datos asociados. Siempre respalda cualquier dato importante antes de eliminar. Esta acción no se puede deshacer.

Patrones comunes

Estas son algunas formas comunes de organizar stacks:

Por proyecto

Un stack por proyecto con todos sus servicios.

saas-app (frontend + api + db + redis)

Por entorno

Stacks separados para staging y producción.

myapp-staging / myapp-production

Por cliente

Las agencias pueden organizar por cliente.

client-acme / client-globex

Servicios compartidos

Infraestructura común en su propio stack.

infrastructure (traefik + monitoring + logging)

Gestión de stacks vía API

Todas las operaciones de stacks están disponibles a través de la API REST. Estos son los endpoints principales:

Terminal

# List all stacks
curl http://localhost:9000/api/projects \
  -H "Authorization: Bearer YOUR_TOKEN"

# Get a specific stack
curl http://localhost:9000/api/projects/STACK_ID \
  -H "Authorization: Bearer YOUR_TOKEN"

# Update a stack
curl -X PUT http://localhost:9000/api/projects/STACK_ID \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "new-name", "description": "Updated description"}'

# Delete a stack
curl -X DELETE http://localhost:9000/api/projects/STACK_ID \
  -H "Authorization: Bearer YOUR_TOKEN"

Note

Para una lista completa de endpoints de la API, consulta la Referencia de la API.

Your First Deploy

Apps & Services