manuais-e-documentacao-itguys/documentacao conteineres/[Nível 1] Gestão De Stacks No Portainer.md

MANUAL TÉCNICO - GESTÃO DE STACKS NO PORTAINER

Código: ITGSUP 0009/26 | Classificação: RESTRITO Responsável: João Pedro Toledo Gonçalves | Data: {{DATA_ATUAL}}

1. HISTÓRICO DE REVISÃO

⚠️ REGRA DE OURO:

1. Autor: João Pedro Toledo Gonçalves.
2. Descrição: Criação do documento.

Data	Versão	Descrição	Autor
{{DATA_ATUAL}}	1.0	Criação Inicial	João Pedro Toledo Gonçalves

2. OBJETIVO

Padronizar o deploy de aplicações (Stacks) no Portainer utilizando três métodos: Upload Manual, Templates de App e Repositório Git (GitOps Básico).

3. PRÉ-REQUISITOS

• Portainer instalado e acessível.
• Um arquivo docker-compose.yml válido E/OU Uma URL de repositório Git (GitHub/GitLab).

4. PASSO A PASSO (EXECUÇÃO)

Etapa 1: Deploy via Web Editor (Rápido)

1. No menu lateral, clique em Stacks -> Add stack.
2. Selecione a opção Web editor.
3. Name: Dê um nome único (ex: meu-nginx).
4. Cole o conteúdo do seu docker-compose.yml na área de texto.
5. Clique em Deploy the stack.

Etapa 2: Deploy via App Templates (Iniciantes)

1. No menu lateral, clique em App Templates.
2. Selecione uma aplicação pronta (ex: "Wordpress" ou "Nginx").
3. Preencha os campos (Nome, Senha do Banco).
4. Clique em Deploy the stack.

Etapa 3: Deploy via Repositório Git (Recomendado/GitOps)

🚀 MELHOR PRÁTICA: Permite versionamento e "Single Source of Truth".

1. Vá em Stacks -> Add stack.
2. Selecione Git Repository.
3. Configuração:
   • Repository URL: https://github.com/usuario/repo.git
   • Repository Reference: main (ou refs/heads/main).
   • Compose path: docker-compose.yml (se estiver na raiz).
4. Authentication (Se privado):
   • Ative "Authentication".
   • Use seu Username e, preferencialmente, um Personal Access Token (não sua senha).
5. Ative Automatic updates (Opcional) para polling.
6. Clique em Deploy the stack.

Etapa 4: Edição e Updates

• Web Editor: Clique na stack -> Editor -> Update the stack.
• Git: Faça o commit no Git -> No Portainer, clique em "Pull and redeploy" (ou aguarde o Auto-update).

5. SOLUÇÃO DE PROBLEMAS (TROUBLESHOOTING)

Problema 1: "Deployment error: Stack already exists"

• Causa: Já existe uma stack com esse nome (mesmo que parada).
• Solução: Delete a stack antiga ou use outro nome.

Problema 2: "Authentication failed" no Git

• Causa: Senha incorreta ou uso de senha ao invés de Token (GitHub exige Token).
• Solução: Gere um PAT (Personal Access Token) no GitHub (Settings -> Developer Settings) e use como senha.

6. DADOS TÉCNICOS

Campo	Valor	Descrição
Padrão	docker-compose.yml	Formato obrigatório
Limit	Stack	Equivalente a um projeto Docker Compose

7. VALIDAÇÃO FINAL

• A stack aparece com status "Active"?
• Os conteineres subiram corretamente?
• Alterar o Git reflete no Portainer (se testado pull)?