Stacks pelo painel do Portainer
Uma stack no Portainer é um conjunto de serviços de um app descrito num arquivo Compose. O painel usa esse arquivo e as variáveis que você informa para implantar os serviços no ambiente escolhido.
Ficha e sumário da página
- Referência técnica
- Portainer 2.45.3
- Revisão
- 13 de novembro de 2026
- Conteúdo
- Documentação oficial consultada
O arquivo Compose dentro do painel
No terminal, uma stack do Compose é uma pasta com o arquivo docker-compose.yml e o arquivo .env. Às vezes a pasta também guarda arquivos de configuração montados nos serviços. O comando docker compose up lê a pasta e cria os recursos. No Portainer, a stack fica ligada a um ambiente. O botão de implantar faz o papel do comando. O painel registra a stack com o nome que você deu a ela.
Para a documentação oficial, uma stack reúne os serviços de um mesmo app. O exemplo citado lá junta um servidor web nginx a um banco MySQL num WordPress. Nos portais da Promovaweb, cada app self-hosted segue esse desenho. A stack do n8n, por exemplo, reúne o próprio n8n e o PostgreSQL que guarda os workflows.
Quatro origens para o mesmo arquivo
O Portainer aceita quatro origens para o arquivo de uma stack nova. O editor web recebe o arquivo digitado ou colado no navegador, com busca e com destaque para caracteres invisíveis, como o espaço não separável que quebra um YAML. O upload envia um arquivo do seu computador. O repositório Git aponta para um arquivo hospedado num repositório, com a branch e o caminho do arquivo. O template personalizado reaproveita um modelo salvo no próprio Portainer.
Seja qual for a origem, a implantação percorre o mesmo caminho até os containers:
Origem
Editor, upload, Git ou templateO arquivo no formato do Compose chega ao painel.
Variáveis
stack.envAs variáveis da stack ficam guardadas fora do arquivo.
Implantação
Deploy the stackO Portainer cria a stack no ambiente escolhido.
Recursos
containers, redes e volumesO Docker cria o que o arquivo descreve.
Uma stack criada pelo editor web permite editar o Compose no próprio Portainer e atualizar a implantação. Nas stacks vinculadas ao Git, você altera o arquivo no repositório. O painel mantém as configurações da conexão e das variáveis, mas a edição do YAML continua no Git enquanto o vínculo existir.
As variáveis ficam fora do arquivo
O arquivo da stack pode citar variáveis no formato ${MINHA_VARIAVEL}, como num Compose com .env. No Portainer, você define essas variáveis uma a uma na tela da stack ou carrega um arquivo .env inteiro. O arquivo Compose não muda quando uma variável muda. Você troca a senha do banco ou o domínio de um app no painel. O YAML continua com a mesma referência à variável.
Num Docker Standalone ou num Podman, o arquivo da stack também aceita stack.env como env_file. Esse nome junta todas as variáveis definidas no painel e as que vieram do .env carregado, para um serviço receber o conjunto inteiro. Num Docker Swarm, segundo a documentação do Portainer, o env_file não funciona, porque o docker stack deploy, usado pelo painel nesse tipo de ambiente, não lê esse campo. No Swarm, cada variável precisa aparecer no arquivo da stack.
A tela da stack também escolhe os registries usados no deploy. Com dois registries do mesmo provedor, como duas organizações no ghcr.io com credenciais diferentes, o Docker pode usar a credencial errada. A escolha explícita do registry evita esse engano.
Atualizações a partir do Git
Uma stack criada a partir de um repositório Git pode receber atualizações automáticas, que a documentação chama de GitOps. O Portainer acompanha o repositório de dois jeitos. No polling, ele consulta o repositório no intervalo configurado. No webhook, ele gera uma URL que o seu repositório chama, por exemplo numa action do GitHub, a cada mudança.
Duas opções completam o comportamento. A primeira baixa de novo as imagens a cada atualização, como o --pull=always, útil para tags como latest ou lts. A segunda força a reimplantação no intervalo configurado mesmo sem mudança no Git, sobrescrevendo qualquer alteração feita direto no ambiente. Com ela ligada, o repositório vira a única referência da stack.
O que fica na Business Edition
Parte dos recursos de stack exige a Business Edition. Os volumes com caminho relativo, que copiam os arquivos do repositório para uma pasta do servidor e permitem montar um arquivo de configuração versionado no Git, são exclusivos dessa edição. O webhook da própria stack, que dispara a reimplantação a partir de um registry como o Docker Hub, também é da Business Edition e não funciona em ambientes Edge. Os recursos e os planos estão na página Community e Business Edition.
Stacks criadas fora do painel
Uma stack subida pelo terminal com docker compose up aparece no Portainer com o controle limitado. O painel não tem o arquivo dela, porque o arquivo ficou na pasta do servidor. Você enxerga os containers e os logs, mas o editor da stack não existe para ela. Para administrar a stack inteira pelo painel, ela precisa ser criada pelo Portainer, por uma das quatro origens.
A remoção de um ambiente também mexe na lista de stacks. As stacks de um ambiente apagado ficam órfãs na lista e voltam a funcionar quando você associa a stack de novo a um ambiente. Os administradores também podem desligar a criação de stacks para os demais usuários, numa configuração de segurança por ambiente.
O Compose de estudo dos portais
O Compose de estudo do n8n reúne o app e o banco, com as variáveis num .env e o acesso web pelo Traefik. No Portainer, você pode carregar essas variáveis na tela da stack. O YAML ainda precisa ser compatível com o ambiente escolhido: um caminho de arquivo da sua máquina não aparece automaticamente no servidor remoto. Um arquivo usado com Compose pode exigir ajustes para Swarm. A seção sobre caminhos relativos explica o recurso da Business Edition para arquivos vindos do Git.
As ações permitidas em cada stack, como criar, editar e remover, dependem das permissões do usuário, assunto da página Usuários, teams e permissões.