Como instalar Portainer e gerenciar containers Docker pela web

Gerenciar dezenas de containers Docker por linha de comando vira fricção rápido: você esquece o nome exato do container, precisa lembrar de flags do docker run, e auditar volumes ou redes pede comandos compostos. O Portainer resolve isso oferecendo uma interface web que cobre 90% das operações do dia a dia — start, stop, logs, exec, criação de stacks docker-compose, gestão de volumes nomeados e redes.

Este tutorial é para quem já tem Docker rodando em um servidor Linux (Ubuntu, Debian ou similar) e quer adicionar uma camada de gerenciamento visual sem reinstalar nada. Vamos instalar a edição Community (CE), proteger a interface com HTTPS auto-assinado que o próprio Portainer gera, criar o usuário administrador e cobrir as operações mais comuns. Tempo estimado: 15 a 25 minutos, dependendo da familiaridade com Docker.

A instalação descrita aqui assume um único host Docker — o cenário mais comum. Se você opera múltiplos servidores Docker e quer um painel central, mencionamos no fim como adicionar agentes remotos depois.

Pré-requisitos

Parâmetros usados ao longo do tutorial:

Se você vai colocar isso em um servidor de produção exposto à internet, considere também ter um domínio apontando para o IP do servidor — facilita futuramente trocar o certificado auto-assinado por um Let’s Encrypt válido via reverse proxy.

Instalação do Portainer Server

A instalação oficial recomendada usa um container Docker dedicado com um volume nomeado pra persistir configuração e dados. Não é preciso clonar repositório nem compilar nada — a imagem oficial cobre todos os casos.

docker volume create portainer_data

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

docker ps --filter "name=portainer"

Primeiro acesso e criação do admin

Com o container rodando, abra o navegador e vá para https://IP_DO_SERVIDOR:9443. O navegador vai alertar sobre certificado não confiável — é esperado, o Portainer gera um certificado auto-assinado na primeira inicialização. Aceite o aviso e prossiga.

Operações cotidianas

O menu lateral à esquerda concentra todas as funções. As três áreas que você vai usar mais são Containers, Volumes e Networks, todas dentro do endpoint local.

Gerenciando containers existentes

A lista de containers mostra nome, estado, imagem base, IP interno e portas expostas. Cada container tem ações inline: start, stop, restart, kill, remove. Clicando no nome do container você acessa:

• Logs — tail ao vivo dos logs com filtro e auto-scroll. Equivalente a docker logs -f.
• Stats — gráficos de CPU, memória, rede e I/O de disco com refresh a cada segundo.
• Console — terminal interativo dentro do container, equivalente a docker exec -it. Aceita escolher o shell (sh, bash) e o usuário.
• Inspect — JSON completo do container, útil pra debug de configuração.

Criando containers pela interface

A tela Add container substitui o docker run. Os campos cobrem todas as flags principais:

• Image: a imagem a usar (pode ser remota tipo nginx:latest ou local)
• Always pull the image: equivalente ao --pull=always
• Port mapping: lista de mapeamentos host:container
• Volumes: bind mounts ou volumes named
• Network: qual rede Docker conectar
• Restart policy: no, on-failure, unless-stopped, always
• Env variables: variáveis de ambiente em par chave/valor
• Capabilities, runtime, devices: parâmetros avançados em abas separadas

Volumes e redes

A seção Volumes lista todos os volumes nomeados, mostra o driver, tamanho consumido e quais containers estão usando cada um. Você pode criar volumes novos com drivers específicos (local, NFS) e remover volumes órfãos com um clique — atalho útil pra liberar espaço em disco depois de remover containers de teste.

A seção Networks mostra as redes Docker (bridge default, host, none, e as que você criar). Criação suporta drivers bridge e overlay, com opção de definir subnet customizada e habilitar IPv6.

Verificação da instalação

Pra confirmar que tudo está funcionando, faça este teste end-to-end:

docker run -d --name teste-portainer nginx:alpine

Recarregue a tela de Containers no Portainer. O container teste-portainer deve aparecer em até 2 segundos. Clique nele, vá em Logs e confirme que vê as linhas de inicialização do nginx. Depois use o botão Remove no Portainer pra apagar — confirme via terminal:

docker ps -a | grep teste-portainer

A saída deve estar vazia. Se o ciclo todo funcionou, instalação está validada.

Resolução de problemas

Erro “Cannot connect to the Docker daemon”

O socket Docker não está montado corretamente no container Portainer. Verifique se a flag -v /var/run/docker.sock:/var/run/docker.sock foi usada no docker run e se o socket existe no host com ls -la /var/run/docker.sock. Em sistemas com SELinux ou AppArmor restritivo, pode ser necessário adicionar :z no final do bind (/var/run/docker.sock:/var/run/docker.sock:z).

Porta 9443 já em uso

Outro serviço escuta nessa porta. Identifique com sudo ss -tlnp | grep 9443 e ou pare o serviço conflitante, ou troque a porta do Portainer recriando o container com -p 9444:9443 (ou qualquer porta livre). O mapeamento interno permanece 9443 — só o lado do host muda.

Browser bloqueia o acesso por certificado inválido

Comportamento esperado em primeira instalação por causa do certificado auto-assinado. Em uso real, coloque o Portainer atrás de um reverse proxy (nginx ou Caddy) com certificado Let’s Encrypt — o proxy faz o TLS público e o Portainer responde HTTP interno na rede Docker.

Próximos passos

Com o Portainer rodando, vale explorar:

1. Criar uma Stack com docker-compose pra subir aplicações multi-container coordenadas
2. Configurar Templates pessoais — receitas pré-prontas com variáveis pra acelerar deploys repetitivos
3. Adicionar um Agent em um segundo servidor pra gerenciar múltiplos hosts pelo mesmo painel
4. Habilitar Registries privados (Docker Hub privado, GitHub Container Registry) na seção Registries
5. Colocar um reverse proxy com Let’s Encrypt na frente pra ter HTTPS válido em domínio próprio

Se você está rodando Portainer em produção pra gerenciar workloads críticos, uma VPS Hostini de plano dedicado dá CPU dedicada e snapshot rápido — útil pra testar updates do Portainer ou rollback de stacks que falharem. Veja as opções em /vps.