Docs / Conceitos Fundamentais / Apps & Serviços

Apps & Serviços

Apps são as unidades implantáveis dentro de uma stack. Cada app roda como um ou mais serviços (containers). Entender essa relação é fundamental para gerenciar seus deploys efetivamente.

Apps vs Serviços

No sh0, a distinção entre um app e um serviço é importante:

App

Um app é uma configuração — define o que fazer deploy, de qual fonte (Git, imagem, template), com quais configurações (vars de ambiente, domínios, limites de recursos). Um app é uma entidade persistente que sobrevive entre deploys.

Serviço

Um serviço é uma instância em execução — o container Docker real criado a partir de um deploy. Serviços são efêmeros. Cada deploy cria um novo serviço e (após verificações de saúde passarem) remove o antigo.

Pense em um app como o blueprint e um serviço como o edifício construído. Quando você refaz deploy de um app, sh0 cria um novo serviço a partir do blueprint atualizado, verifica que funciona e então derruba o serviço antigo.

Diagram showing an App box containing configuration (Git URL, env vars, domain), with arrows pointing to Service v1 (old, being removed) and Service v2 (new, running)

Apps persist across deployments; services are recreated each time

Ciclo de Vida do App

Um app passa por vários estados durante seu ciclo de vida, da criação ao deploy ativo:

Estados do Ciclo de Vida

Estado	Badge	Descrição
Criado	Gray	App está configurado mas nunca foi implantado.
Construindo	Blue	Código-fonte está sendo clonado e a imagem do container está sendo construída.
Implantando	Yellow	Container está iniciando e verificações de saúde estão rodando.
Rodando	Green	App está online e servindo tráfego. Verificações de saúde estão passando.
Parado	Gray	App foi parado manualmente. Container não está rodando.
Falhou	Red	Build ou deploy falhou. Versão anterior continua rodando se disponível.

App list showing apps in different states: 'frontend' with a green Running badge, 'worker' with a yellow Deploying badge, and 'migration-job' with a gray Stopped badge

Apps display their current lifecycle state

Deploys Sem Downtime

Quando um app está no estado Rodando e você aciona um novo deploy, sh0 usa uma estratégia blue-green. O serviço antigo continua tratando tráfego enquanto o novo constrói e inicia. O tráfego só troca após o novo serviço passar sua verificação de saúde. Se o novo serviço falhar, o antigo permanece ativo.

Criando um App

Apps são criados dentro de uma stack. Navegue até uma stack e clique em Add App. Você pode criar apps a partir de três fontes:

Repositório Git -- Forneça uma URL, e sh0 clona, detecta a stack, constrói e faz deploy automaticamente.
Imagem Docker -- Baixar e executar uma imagem existente do Docker Hub, GitHub Container Registry ou qualquer registry privado.
Template -- Escolha entre mais de 170 templates pré-configurados para aplicações populares.

Add App dialog showing three source options as cards: Git Repository with a branch icon, Docker Image with a container icon, and Template with a grid icon

Choose your app source

Configurações do App

Cada app tem um painel de configurações abrangente organizado em várias categorias.

Configurações Gerais

Nome -- O identificador do app dentro da stack. Também usado como nome do container Docker e hostname interno.
Porta -- A porta que sua aplicação escuta dentro do container. sh0 roteia tráfego externo para esta porta.
Fonte -- A URL Git, imagem Docker ou configuração de template.
Branch -- Para apps baseados em Git, o branch a rastrear e fazer deploy.
Auto-deploy -- Quando habilitado, pushes para o branch rastreado acionam deploys automáticos.

Configurações de Build

Comando de Build -- Sobrescrever o comando de build padrão (ex.: npm run build).
Comando de Início -- Sobrescrever o comando de início padrão (ex.: node server.js).
Caminho do Dockerfile -- Usar um Dockerfile personalizado em vez do gerado automaticamente pelo sh0.
Build Arguments -- Passar variáveis de build-time para o processo de build Docker.

App settings page showing the Build Settings section with fields for Build Command, Start Command, Dockerfile Path, and Build Arguments

Customizing build and start commands

Limites de Recursos

Você pode definir limites de CPU e memória em cada app para prevenir que uma única aplicação consuma todos os recursos do servidor:

Configuração	Padrão	Descrição
Limite de CPU	Sem limite	Máximo de cores CPU que o container pode usar (ex.: 0.5, 1, 2)
Limite de Memória	Sem limite	RAM máxima (ex.: 256m, 512m, 1g). Container é morto se excedido.
Reserva de Memória	Sem limite	Limite suave. Docker tenta manter o container próximo deste valor.

Setting Limits via API

curl -X PUT http://localhost:9000/api/apps/APP_ID \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"cpu_limit": 1.0, "memory_limit": "512m"}'

Falta de Memória

Quando um container excede seu limite de memória, o Docker o mata imediatamente (OOMKilled). Se seu app frequentemente atinge o limite, aumente a alocação ou investigue vazamentos de memória. Verifique a seção de Monitoramento para gráficos de uso de memória.

Políticas de Reinício

Políticas de reinício determinam o que acontece quando um container para ou trava:

Política	Comportamento
`always`	Sempre reiniciar o container, independente do código de saída. Padrão para apps.
`on-failure`	Reiniciar apenas se o container sair com código de saída diferente de zero.
`unless-stopped`	Reiniciar a menos que explicitamente parado pelo usuário.
`no`	Nunca reiniciar. Útil para tarefas únicas como migrações.

Tip

Para serviços de longa duração (servidores web, APIs), use always. Para jobs únicos (migrações de banco, scripts seed), use no para que o container pare após a tarefa completar.

Verificações de Saúde

Verificações de saúde conferem que seu app está funcionando corretamente após o deploy. sh0 suporta dois tipos:

Verificação de Saúde HTTP -- sh0 envia uma requisição HTTP GET para um caminho especificado (padrão: /) e espera uma resposta 2xx.
Verificação de Saúde TCP -- sh0 verifica que o container está ouvindo na porta configurada. Usado para serviços não-HTTP.

Health Check Configuration

{"health_check": {"type": "http", "path": "/health", "interval": 10, "timeout": 5, "retries": 3, "start_period": 30}}

App health check settings showing type selector (HTTP/TCP), path field, interval, timeout, retries, and start period fields with sensible defaults

Configuring health checks for your app

Note

Durante o deploy, sh0 aguarda a verificação de saúde passar antes de rotear tráfego para o novo container. Se a verificação de saúde falhar após as tentativas configuradas, o deploy é marcado como falho e a versão anterior continua servindo tráfego.

Stacks

Domains & SSL