Docs / Conceitos Fundamentais / Stacks

Stacks

Uma stack é a unidade organizacional de nível superior no sh0. Ela agrupa aplicações e serviços relacionados, fornecendo configuração compartilhada e uma visão unificada do seu projeto.

O que é uma Stack?

Uma stack representa um projeto ou produto composto por uma ou mais aplicações e serviços. Por exemplo, uma stack típica de aplicação web pode incluir:

Uma aplicação frontend (React, Vue, Svelte)
Uma API backend (Node.js, Python, Go)
Um banco de dados PostgreSQL
Um cache Redis
Um worker em segundo plano

Tudo isso fica dentro de uma stack, compartilha variáveis de ambiente e pode se comunicar por uma rede Docker privada. Quando você abre uma stack no painel, vê todos os seus componentes de uma só vez.

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 Apps vs Serviços

Entender a hierarquia é importante:

Conceito	Descrição	Exemplo
Stack	Um agrupamento de projeto ou produto	"E-commerce Platform"
App	Uma unidade implantável dentro de uma stack	"api", "frontend", "worker"
Serviço	Uma instância de contêiner em execução de uma aplicação	"api-v3-abc123" (container)

Uma stack contém uma ou mais aplicações. Cada aplicação roda como um ou mais serviços (contêineres). Quando você implanta uma aplicação, o sh0 cria um novo serviço (contêiner) e opcionalmente remove o antigo após o health check passar.

Note

Todas as aplicações dentro de uma stack compartilham uma rede Docker, o que significa que podem se comunicar usando o nome da aplicação como hostname. Por exemplo, seu frontend pode acessar a API em http://api:3000 sem nenhuma configuração extra.

Criando uma Stack

Existem duas formas de criar uma stack:

Pelo Painel:

Clique em Nova Stack no canto superior direito ou na página de stacks.
Insira um nome (apenas minúsculas, alfanumérico e hífens).
Adicione uma descrição opcional.
Clique em Criar Stack.

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

Creating a new stack from the dashboard

Pela 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"}'

Visualização Detalhada da Stack

Clicar em uma stack abre a visualização detalhada, que fornece uma visão completa do seu projeto:

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

Aba Apps -- Todas as aplicações nesta stack com seu status, uso de recursos e ações rápidas (implantar, reiniciar, parar).
Aba Ambiente -- Variáveis de ambiente em nível de stack compartilhadas entre todas as aplicações.
Aba Domínios -- Todos os domínios atribuídos a aplicações nesta stack.
Aba Backups -- Agendamentos e histórico de backup para bancos de dados nesta stack.
Aba Configurações -- Nome da stack, descrição, zona de perigo (excluir stack).

Variáveis de Ambiente da Stack

Variáveis de ambiente em nível de stack são herdadas por todas as aplicações na stack. Isso é útil para configurações compartilhadas como chaves de API, URLs de banco de dados ou feature flags que se aplicam a todo o projeto.

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

Precedência de Variáveis

Variáveis de ambiente em nível de aplicação sobrescrevem as de nível de stack. Se uma stack define APP_ENV=production e uma aplicação define APP_ENV=staging, a aplicação usa staging. Isso permite compartilhar padrões enquanto permite sobrescritas por aplicação.

Configurações da Stack

A aba Configurações permite modificar os metadados da stack e realizar ações administrativas:

Nome e Descrição -- Atualizar o nome de exibição e a descrição da stack.
Rede Docker -- Visualizar o nome da rede Docker interna desta stack.
Zona de Perigo -- Excluir a stack e todas as suas aplicações, serviços e dados. Esta ação é irreversível.

Excluindo uma Stack

Excluir uma stack remove todas as aplicações, contêineres, volumes e dados associados. Sempre faça backup dos dados importantes antes de excluir. Esta ação não pode ser desfeita.

Padrões Comuns

Aqui estão algumas formas comuns de organizar stacks:

Por Projeto

Uma stack por projeto com todos os seus serviços.

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

Por Ambiente

Stacks separadas para staging e produção.

myapp-staging / myapp-production

Por Cliente

Agências podem organizar por cliente.

client-acme / client-globex

Serviços Compartilhados

Infraestrutura comum em sua própria stack.

infrastructure (traefik + monitoring + logging)

Gerenciando Stacks via API

Todas as operações de stack estão disponíveis pela API REST. Aqui estão os principais endpoints:

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 uma lista completa dos endpoints da API, consulte a Referência da API.

Your First Deploy

Apps & Services