Chega a um ponto em que o servidor corre uma dezena de containers do Docker — o GLPI, o WordPress, o Vaultwarden e mais meia dúzia de serviços dos guias daqui — e a gestão passa por SSH e docker ps a cada consulta. Funciona, mas diagnosticar um serviço parado à hora do jantar passa a ser um trabalho de memória. O Portainer resolve isso: uma interface web que centraliza o estado de containers, imagens, volumes e redes de um servidor Docker ou de dezenas, com botões para tudo o que o CLI faz — e registo de quem fez o quê.

⚠ Antes de produção: o Portainer gere o Docker através do socket do daemon (/var/run/docker.sock), que é o controlo total do motor — quem entra na interface faz o que o root faz no host. Testa primeiro num servidor de testes e protege a porta com HTTPS e firewall antes de abrires à equipa.

Instalação no servidor Docker

O Portainer corre como um container no Docker que vai gerir. Na versão Community Edition, a instalação resume-se a dois comandos — um volume para a base de dados e o container com o socket montado:

docker volume create portainer_data
docker run -d -p 8000:8000 -p 9443:9443 --name portainer --restart=always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v portainer_data:/data portainer/portainer-ce:lts

A porta 9443 abre a interface em HTTPS (com certificado autoassinado na primeira utilização) e a 8000 é só o túnel para os Edge Agents — dispensável se não fores usar esse modo. Escolhe uma das duas vias — os comandos seguintes criam um segundo Portainer com o mesmo nome e as mesmas portas, por isso não correm os dois caminhos. Para instalar por Compose, descarrega o stack oficial — o ficheiro portainer-compose.yaml do site de downloads da Portainer:

curl -L https://downloads.portainer.io/ce-sts/portainer-compose.yaml -o portainer-compose.yaml

E levantar o serviço a partir do ficheiro:

docker compose -f portainer-compose.yaml up -d

A porta 9000 em HTTP deixou de ser pré-publicada: só aparece se adicionares -p 9000:9000 por razões de legacy.

Depois de docker ps confirmar o container a correr, o endereço https://IP-DO-SERVIDOR:9443 abre o primeiro arranque.

Primeiro acesso

A primeira abertura pede a criação da conta de administração — guarda a password com calma: em CE não há recuperação por e-mail. Perdeu-a? A própria Portainer publica uma imagem de recuperação (portainer/helper-reset-password): pára o container, corre o helper — gera uma password nova para o admin sem perder os dados do volume — e volta a arrancar. Desde a 2.43, o primeiro acesso pede também o setup token — um código de utilização única que a instância imprime nos logs (docker logs portainer | grep setup_token) para impedir que um desconhecido reclame a instalação antes de ti. Há flags –setup-token e –no-setup-token (e –admin-password) para automatizar. Se o ecrã de setup expirar (são 5 minutos entre o arranque do container e o primeiro acesso), basta reiniciar o container. De seguida, escolher Get Started para gerir o Docker local com o socket montado — o ambiente aparece como local.

O ecrã de Dashboard resume o ambiente: containers a correr e parados, imagens, volumes e redes. À direita, os Endpoints (na terminologia actual, Environments): cada servidor Docker adicionado fica aqui listado.

Containers, imagens e volumes no dia a dia

Tudo o que se usa numa semana de administração está a um clique na sidebar:

  • Containers — lista com estado, imagem, portas e a acção rápida (start, stop, restart, kill, remove). O Logs de cada container mostra o stdout/stderr com filtro e um download. O Console abre um shell dentro do container (bash, sh ou comando personalizado) — a inspecção que costumava ser docker exec -it. Stats mostra CPU, memória e rede em directo por container.
  • Imagens — pull de novas versões por nome (ex. glpi/glpi), limpeza de imagens órfãs e a lista de layers. Depois do pull, o restart do container com recreate aplica a nova imagem quando o compose define pull_policy ou na stack.
  • Volumes — os dados persistentes dos serviços (a base do GLPI, o wp-content) listados com o tamanho via browse, com um explorador de ficheiros que copia/renomeia/apaga dentro do volume.
  • Redes — as redes definidas pelo Compose e as do sistema, com a lista de containers ligados a cada uma.
  • Eventos — o registo das acções feitas na interface (start, stop, create, login) com autor e data, o mínimo de auditoria que uma equipa partilhada precisa.

Na prática, o ciclo de actualização corre da interface: em stacks ligadas a um repositório Git, o botão Pull and redeploy puxa o último commit e recria os services. Em stacks do editor, editas o YAML e a stack reaplica-se ao guardar. Quem prefere manter o compose no disco continua a poder editar pelo terminal: o Portainer não trava os comandos normais do Docker.

Stacks: Compose pelo browser

No menu Stacks vive a parte mais útil para quem já usa Compose: cada stack é um projecto do Docker Compose editado, actualizado e re-deployado pela interface — com o editor a guardar a versão, o Editor a fazer highlight de YAML e o botão Update the stack a executar o equivalente de docker compose up -d

As variáveis do .env (passwords, paths) editam-se em formulário sem tocar no YAML, e os Templates (App Templates) preparam deployments de aplicações conhecidas — WordPress, Nginx, Registry — que se personalizam antes de aplicar. O historial de versões do editor permite reverter um update que partiu algo.

Vários servidores com o Agent

Numa PME com mais de um host Docker — o servidor principal e o NAS, por exemplo — o modelo é o mesmo container do Portainer num host e o Agent nos restantes: um container leve que expõe o Docker daquela máquina ao Portainer. O Environments da sidebar adiciona cada agente por host:9001, e o dashboard passa a agregar todos. Para sedes em locais distintos, os Edge Agents ligam-se do exterior para o Portainer (o túnel da porta 8000), sem necessidade de portas abertas no agente.

docker run -d \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /var/lib/docker/volumes:/var/lib/docker/volumes \
  --restart=always \
  -p 9001:9001 \
  --name portainer_agent portainer/agent:lts

O agente só fala com o Portainer que o instalou (chave de autenticação trocada no registo do endpoint) e não expõe o socket para a rede — o que sai do host é a metadados e o fluxo das operações pedidas.

Dockge: alternativa só-Compose

Se os teus containers vivem todos em ficheiros compose.yaml e o que te falta é um sítio cómodo para os editar e arrancar, o Dockge (do autor do Uptime Kuma) cumpre isso com o mínimo: gere apenas stacks de Compose — não gere imagens nem redes directamente (os volumes e redes que o compose define são criados com a stack) e o multi-host só aparece no modo agente da 1.4.0. Os ficheiros continuam em disco como sempre estiveram, em /opt/stacks, editáveis por terminal sem o Dockge saber — a base de dados da interface não os “sequestra”.

A instalação é um compose próprio, com a interface na porta 5001:

mkdir -p /opt/stacks /opt/dockge
cd /opt/dockge
curl https://raw.githubusercontent.com/louislam/dockge/master/compose.yaml \
  --output compose.yaml
docker compose up -d

No dia a dia, o Dockge dá-te:

  • Editor reactivo de YAML com terminal web integrado (docker compose dentro do browser).
  • Conversão de docker run para compose.yaml — colas o comando e ele escreve o ficheiro.
  • Multi-agent (1.4.0+) — vários hosts Docker na mesma interface.
  • Ficheiros no teu disco — o que vês é o que está em /opt/stacks.

Instala-o quando a gestão se resume a stacks de Compose. Se precisares de imagens, volumes, registos e eventos na mesma interface, regressa ao Portainer — as duas ferramentas convivem no mesmo servidor sem conflito.

Boas práticas

  • O socket é o reino — quem controla a interface controla o Docker com os poderes do root do host. Por isso o 9443 não se abre à internet: a interface fica atrás da VPN (o WireGuard dos guias daqui) ou de um Reverse Proxy com autenticação, e a firewall do host limita a origem.
  • Mantém o Portainer actualizado — o registo NVD mostra falhas recentes na CE (um bypass de autenticação em instâncias não inicializadas, 2.39.0–2.39.3 e 2.40.0–2.42.x, e o CVE-2026-44883, com tokens JWT em query string). Uma actualização de dois minutos fecha as janelas conhecidas.
  • MFA — a CE não traz TOTP próprio: fica atrás de um Reverse Proxy com MFA (Authelia/Authentik) ou do acesso por VPN, onde vive o segundo factor.
  • Backup do volume — portainer_data contém utilizadores, endpoints e definições, e entra no backup diário do servidor (a juntar ao resto de que já fazes backup).
  • Contas individuais — cada pessoa da equipa com utilizador próprio (CE suporta equipas e atribuição por ambiente) e os Eventos a valer de registo. O RBAC granular (roles Helpdesk/Operator por ambiente) existe na Business Edition, não na CE.
  • Revisões do editor — antes de aplicar um update a uma stack em produção, validar num ambiente de testes. O que o botão faz é um up -d real.

Erros comuns

  • docker.sock permission denied — o container não arranca com o socket. Em Docker rootless, o Portainer exige configuração extra na origem do socket. Com SELinux activo em RHEL/Alma, o arranque pede --privileged ou o mapeamento certo.
  • Setup expirado — se a página inicial de criação da conta demorar mais de 5 minutos, o container cai em timeout — docker restart portainer e abrir de novo.
  • Certificate unknown (browser) — o 9443 usa certificado autoassinado na primeira utilização: aceitar o aviso ou instalar o teu certificado próprio.
  • Stack não arranca — a falta de variáveis obrigatórias no .env é a causa mais frequente: o log da stack (não do container) indica qual.
  • Agente não regista — o portainer/agent só aceita o Portainer que gerou a chave. Se o volume portainer_agent:/data foi recriado, remover e voltar a adicionar o endpoint.

Veredicto

Para quem gere o Docker todos os dias pelo terminal: é a camada que faz falta quando o Docker deixa de ser um container e passa a ser um parque. As operações diárias ficam auditáveis e delegáveis (a equipa vê logs e reinicia serviços sem SSH), o compose continua a mandar na configuração, e o Dockge cobre o nicho de quem só quer stacks. Instala-se em dois comandos e não prende nada do Docker — a reversão é apagar o container e o volume.

💡 Regra prática: gere pela interface, versiona pelo Git. O Portainer guarda o estado do ambiente — os stacks continuam a ser ficheiros YAML: entram no backup do servidor, como qualquer ficheiro de configuração.

Artigos Relacionados

Fontes oficiais