Ir para o conteúdo
Promovaweb

O que é o Portainer e para que serve

O Portainer é um painel web para administrar containers e stacks. Pelo socket local do Docker ou por um agente, você consulta os logs e altera os apps da sua VPS no navegador.

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
  1. Um container que conversa com o Docker
  2. O que muda numa VPS com várias stacks
  3. Um Server, vários ambientes
  4. A instalação inicial e o token de setup
  5. Duas edições sobre a mesma base
  6. Limites do Portainer

Um container que conversa com o Docker

O Portainer tem duas peças, o Portainer Server e o Portainer Agent. As duas rodam como containers leves. Numa VPS única, o Server basta. Ele recebe o socket do Docker montado como volume e, por esse arquivo, faz as mesmas chamadas que o comando docker faz quando você lista containers ou sobe uma stack no terminal. Um container criado pelo terminal aparece na lista do Portainer, assim como um container criado pelo painel aparece no docker ps.

O Server também precisa de um volume próprio. Nele ficam o banco do Portainer, com os usuários, os ambientes cadastrados e as configurações, além dos arquivos das stacks criadas pelo painel. A instalação oficial da Community Edition monta esse volume em /data e publica duas portas:

  • portainer/portainer-ce:ltsA imagem do Portainer Server na linha LTS.
  • /var/run/docker.sockO socket do Docker do servidor, montado no container.
  • portainer_data:/dataO banco de configurações e os arquivos das stacks.
  • 9443A interface em HTTPS, com certificado autoassinado gerado na instalação.
  • 8000O servidor de túnel para os Edge Agents, opcional.
  • 9000A interface em HTTP, a porta que um proxy reverso usa na rede interna.
O container do Portainer Server na instalação oficial da Community Edition 2.45 LTS. A porta 8000 só tem uso com Edge Agents. A 9000 atende HTTP dentro da rede Docker.

A interface que você abre no navegador é servida pelo mesmo container. Não existe banco externo nem serviço adicional para instalar, o que mantém a stack do Portainer pequena perto das stacks que ele administra.

O que muda numa VPS com várias stacks

Com uma stack só, o terminal atende bem. Com várias stacks na mesma VPS, cada uma com o próprio Compose, os seus logs e as suas variáveis, a leitura do estado do servidor exige uma sequência de comandos para cada app. O Portainer reúne essa leitura numa tela por ambiente, com o total de stacks, de containers rodando e parados, de imagens com o espaço ocupado em disco, de volumes e de redes.

Um container que reiniciou durante a noite mostra as duas formas de investigar a mesma falha:

Pelo terminal

  • Você entra na VPS por SSH e lista os containers com docker ps -a.
  • Os logs saem do docker logs, um container por vez.
  • O console do container abre com docker exec.
  • As variáveis da stack ficam no arquivo .env da pasta do Compose.

Pelo Portainer

  • A lista de containers mostra o estado e a saúde de cada um no navegador.
  • Os logs abrem na tela do container, sem sair do navegador.
  • O console abre na mesma tela, dentro do navegador.
  • As variáveis da stack ficam guardadas no Portainer, junto com o arquivo Compose.

O terminal e o painel acessam o mesmo Docker. Você pode investigar um container com docker logs ou pela tela de logs do Portainer, conforme a forma de acesso disponível naquele momento. A criação e a execução dos containers continuam a cargo do Docker.

Um Server, vários ambientes

O Portainer chama de ambiente cada Docker, Docker Swarm, Podman ou cluster Kubernetes que ele administra. Na instalação, o assistente detecta o Docker local pelo socket e cadastra esse primeiro ambiente. Os outros servidores entram pelo Portainer Agent ou pelo Edge Agent. Depois de cadastrados, todos eles aparecem na tela inicial do mesmo painel.

A documentação recomenda um único Portainer Server por conjunto de ambientes, rodando num servidor de gerência, com os agentes nos demais servidores. Os agentes não guardam estado. Tudo o que eles leem volta para o Server, que mantém o banco no volume /data. A página Ambientes e agentes explica cada forma de conexão.

A instalação inicial e o token de setup

Um Portainer recém-criado ainda não tem administrador. O primeiro acesso à interface define esse usuário. Desde as versões 2.43 e 2.39.4, a tela de configuração inicial exige um token de setup, que o Server escreve nos próprios logs na linha setup_token=. Você copia o token do docker logs do container e cria o administrador com uma senha de pelo menos 12 caracteres.

O Server também espera esse primeiro cadastro por 5 minutos. Sem administrador criado nesse prazo, ele para de atender requisições até o container reiniciar. As duas proteções existem porque o painel controla o Docker inteiro. Uma instalação exposta na internet sem administrador ficaria disponível para o primeiro acesso que chegasse.

Duas edições sobre a mesma base

A Portainer.io mantém o Portainer em duas edições. A Community Edition é gratuita e de código aberto, publicada sob a licença zlib. É a edição abordada neste portal. A Business Edition exige uma chave de licença, com opção gratuita para três nodes e planos pagos por node. Ela acrescenta o controle de acesso por papéis e recursos de gestão de registries. O suporte comercial depende do plano contratado. As duas compartilham a arquitetura de Server e agentes, mas usam imagens diferentes. Os limites estão detalhados na página Community e Business Edition.

Limites do Portainer

O Portainer não publica o seu app na internet. O domínio, o certificado HTTPS e o roteamento continuam com o proxy reverso. Nos portais da Promovaweb, esse papel é do Traefik. O próprio painel também fica atrás do Traefik, num domínio com HTTPS, como explica a página O Portainer atrás do Traefik.

O painel também não guarda cópia dos volumes das suas stacks. O banco do Portainer registra as stacks e as configurações dele, mas os arquivos de um banco PostgreSQL ou de um n8n continuam nos volumes do Docker, com a cópia de segurança sob a sua responsabilidade. Segundo a documentação oficial, a interface está disponível só em inglês. Os nomes das telas citados nestas páginas seguem a grafia original.

O passo seguinte é conhecer o que cada tela do painel mostra dentro de um ambiente, na página O que o Portainer gerencia.

StayCloud

Uma VPS para desenvolver com agentes

Servidor da StayCloud em São Paulo, com acesso root e disco NVMe, para deixar seus agentes de IA rodando o dia todo.

Montar minha VPS

Link de parceiro da Promovaweb.