Como usar o Portainer para gerenciar containers Docker (passo a passo)

Ferramentas & Produtividade · Por · Publicado em · Atualizado em · 8 min de leitura

Monitor com terminal em destaque e uma lista de serviços desfocada
Tela com terminal e lista de serviços, ilustrando administração de containers Foto: Brett Sayles / Pexels

Este guia mostra, na prática, como usar o Portainer para gerenciar containers Docker: da instalação ao deploy de stacks, controle de volumes e redes, logs e segurança. Em poucos passos, você terá um painel web para operar seus ambientes locais ou remotos com mais segurança e menos comandos na mão.

O que é o Portainer e quando ele ajuda

Portainer é um painel web que simplifica a administração de ambientes Docker. Ele reduz erros em tarefas operacionais e padroniza deploys via UI ou stacks (Compose).

É útil quando sua equipe precisa:

- Visualizar containers, volumes e redes de forma centralizada.

- Padronizar deploys com Compose, sem depender só de CLI.

- Gerenciar múltiplos hosts locais e remotos.

Se você ainda avalia quando usar containers em vez de VMs, veja um comparativo prático em Docker vs máquinas virtuais para HA.

Pré-requisitos e ambiente de teste

Antes de começar, garanta:

- Um host com Docker Engine instalado e acesso sudo.

- Portas de rede liberadas: 9443/TCP para a UI; 9001/TCP para o Agent remoto.

- Navegador atualizado para acessar o painel web.

- Opcional: um segundo host Docker para testar o Agent remoto.

Atenção: mapear o arquivo /var/run/docker.sock para containers dá acesso administrativo ao Docker. Use apenas em hosts confiáveis e aplique controles de acesso na rede e no sistema.

1) Instalar o Portainer CE no host Docker

A instalação mínima usa um volume persistente para os dados do Portainer e publica a interface segura na porta 9443. Exige acesso root ou sudo.

Execute os comandos abaixo no host que já possui Docker. Aguarde o container iniciar e confira se a porta 9443 está acessível na sua rede local.

# 1) Criar volume persistente para dados do Portainer
sudo docker volume create portainer_data

# 2) Subir o Portainer CE com HTTPS (9443)
sudo docker run -d \
  -p 9443:9443 \
  --name portainer \
  --restart=always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v portainer_data:/data \
  portainer/portainer-ce:latest

# 3) Verificar status
sudo docker ps --filter name=portainer
# Acesse https://SEU_HOST:9443 no navegador (certificado pode ser autoassinado).

2) Primeiro acesso e criação do usuário administrador

Acesse https://SEU_HOST:9443 no navegador. Na primeira tela, defina o usuário e a senha do administrador.

Em seguida, escolha o tipo de ambiente a gerenciar. Para começar, selecione o próprio Docker local (Local). Você verá o dashboard com containers, imagens, volumes e redes.

Boas práticas iniciais:

- Crie uma senha forte e armazene-a em um cofre de senhas.

- Desative portas públicas que não serão usadas. Prefira expor via VPN ou túnel seguro.

- Crie tags e grupos de ambientes para organizar hosts.

3) Conectar hosts remotos com o Portainer Agent

Para gerenciar servidores Docker remotos, instale o Portainer Agent em cada host e conecte-os pelo painel. Abra a porta 9001/TCP no firewall e garanta que somente o Portainer possa acessá-la.

No host remoto, rode o Agent. Depois, no Portainer, adicione um novo ambiente do tipo Agent e informe o endereço do host remoto:9001.

# No host REMOTO (com Docker instalado)
sudo docker run -d \
  -p 9001:9001 \
  --name portainer_agent \
  --restart=always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /var/lib/docker/volumes:/var/lib/docker/volumes \
  portainer/agent:latest

# Após subir, no Portainer UI: Environments > Add environment > Agent
# Informe: tcp://IP_DO_HOST_REMOTO:9001

4) Deploy de containers e stacks (Compose)

Você pode subir containers individuais ou stacks usando arquivos Compose. Stacks facilitam versionamento e replicação entre ambientes.

Fluxo comum:

- Criar uma stack, colar o YAML do Compose, ajustar variáveis e deployar.

- Parametrizar variáveis com .env e Secrets.

- Validar logs e saúde do serviço após o deploy.

A tabela abaixo ajuda a localizar ações típicas na UI e seu equivalente conceitual na CLI.

Tarefa Onde na UI Equivalente na CLI
Subir container único Containers > Add container docker run
Subir stack Compose Stacks > Add stack docker compose up -d
Mapear porta/volume Form de container/stack -p / -v
Ver logs Container > Logs docker logs -f
Reiniciar/escala Container/Stack > Actions docker restart / compose scale 
# Exemplo de stack (Compose v3+): Web + Redis
a version: "3.8"
services:
  web:
    image: nginx:alpine
    ports:
      - "8080:80"
    volumes:
      - web_content:/usr/share/nginx/html:ro
    depends_on:
      - cache
  cache:
    image: redis:7-alpine
    command: ["redis-server", "--appendonly", "yes"]
    volumes:
      - redis_data:/data
volumes:
  web_content: {}
  redis_data: {}

Volumes, redes, variáveis e segurança na prática

Volumes: prefira volumes nomeados para persistência. Para backup, copie os dados fora do host ou compacte o volume periodicamente.

Redes: use redes bridge personalizadas por projeto para isolar tráfego entre serviços. Evite compartilhar redes sem necessidade.

Variáveis e secrets: armazene credenciais como Secrets e use variáveis de ambiente para parâmetros. Não coloque senhas direto na imagem.

Segurança:

- Restrinja o acesso à UI (9443) por VPN, IP allowlist ou proxy reverso.

- Ative HTTPS e evite expor a porta 9001 publicamente.

- Revise quem pode tocar no Docker socket e no host.

Automação: após dominar o básico, conecte seus deploys a pipelines de CI/CD. Veja um guia prático em CI/CD com GitHub Actions (PHP/Laravel) para adaptar ao seu stack.

Logs estruturados ajudam muito no diagnóstico. Se você ainda não padroniza logs, confira o guia de logs estruturados (JSON) e correlação.

# Exemplos úteis (executar no host conforme seu ambiente)

# Backup simples do volume do Portainer (gera arquivo no diretório atual)
sudo docker run --rm \
  -v portainer_data:/data \
  -v "$(pwd)":/backup \
  alpine sh -c "tar czf /backup/portainer_data.tgz -C / data"

# Atualizar o Portainer mantendo os dados
sudo docker pull portainer/portainer-ce:latest
sudo docker stop portainer && sudo docker rm portainer
sudo docker run -d -p 9443:9443 \
  --name portainer --restart=always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v portainer_data:/data \
  portainer/portainer-ce:latest

Verificação do ambiente e solução de problemas comuns

Após instalar e configurar, valide se tudo está saudável:

- A UI abre em https://SEU_HOST:9443 sem erros críticos.

- Você vê containers, volumes e redes do host Local.

- O Agent remoto aparece em Environments com status up.

- Logs do container de teste não mostram falhas recorrentes.

Problemas comuns e correções:

- Porta 9443/9001 bloqueada: libere no firewall e no provedor.

- Permissões no Docker socket: o processo precisa acesso ao /var/run/docker.sock.

- DNS e pull de imagens: verifique rede externa do host.

- Certificado autoassinado: adicione exceção temporária ou use proxy com TLS válido.

- Em WSL2/desktop, confirme o IP correto do host.

Para maturidade de operação e auditoria de mudanças de deploy, vale estudar processos e checklists como os discutidos em auditoria de processos de deploy.

# Verificações rápidas
sudo docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}" | sed -n '1,10p'

# Logs do Portainer (últimas 100 linhas)
sudo docker logs --tail=100 portainer

# Testar conectividade com Agent remoto (da máquina do Portainer)
# Substitua IP_PEER pelo endereço do host remoto
nc -vz IP_PEER 9001 || telnet IP_PEER 9001 || echo "Falha na conexão"

Perguntas frequentes

Posso usar o Portainer em produção?

Sim, muitos times usam para operar e padronizar ambientes. A decisão depende dos requisitos de segurança, governança e automação. Restrinja acesso à UI, use HTTPS e limites de rede, e teste em um ambiente de homologação antes de adotar amplamente.

O Portainer substitui o docker-compose?

Não. Ele orquestra stacks baseadas em Compose e facilita o deploy pelo painel. Você continua usando o mesmo arquivo YAML. A vantagem é visualizar, parametrizar e versionar stacks com menos fricção na operação diária.

Como proteger o acesso ao Docker socket?

Evite expor o socket pela rede. Mantenha-o montado apenas localmente para o Portainer e restrinja quem tem acesso ao host. Use princípios de menor privilégio, atualize o sistema e audite contas e chaves regularmente.

Preciso de Kubernetes para usar o Portainer?

Não. Ele gerencia Docker puro muito bem. Se no futuro você migrar para Kubernetes, o Portainer também oferece suporte, mas você pode começar e operar apenas com Docker sem problemas.

Como faço backup dos dados do Portainer?

Os dados ficam no volume mapeado em /data. Faça backup recorrente desse volume, copiando-o para armazenamento externo. Você pode usar um container temporário para compactá-lo ou outra ferramenta de backup do seu ambiente.

É possível integrar com CI/CD?

Sim. Você pode disparar deploys de stacks via automação ou scripts que atualizam imagens e reiniciam serviços. Planeje variáveis, secrets e promoção entre ambientes. Veja ideias no guia de CI/CD citado.

Pronto para operar seus containers com menos atrito?

Siga o passo a passo, teste em um ambiente isolado e evolua com logs estruturados, backup e automação de deploys. Comece hoje pelo ambiente local e conecte seus hosts remotos com o Agent.

Revisar comandos e iniciar agora

Veja também