- dezembro 10, 2025
- 12:59 pm
Administrar o Docker pela CLI não é algo complexo, porém para quem está começando e até mesmo para ter uma visão mais ampla do ambiente, uma interface web torna tudo mais intuitivo e simples de gerenciar. E é exatamente aí que o Portainer se destaca.
DICA IMPORTANTE
Ter uma interface web é excelente para facilitar o gerenciamento, porém é importante não depender exclusivamente dela. Em caso de falhas ou indisponibilidade da aplicação, saber utilizar o CLI garante que você conseguirá analisar e manter o ambiente funcionando.
Lembrando que parte das informações apresentadas foram extraídas da documentação oficial do Portainer. No post anterior configuramos um cluster com Docker Swarm, e agora iremos instalar o Portainer com um agente em cada Node do cluster para facilitar a gestão do ambiente.
Caso você não tenha um cluster Swarm e esteja utilizando apenas o Docker em um servidor isolado, também é possível instalar o Portainer sem o agente. Nesse cenário, a conexão entre o Portainer e o serviço Docker ocorrerá diretamente pela Docker API.
Quer montar seu ambiente Docker Swarm?
Aprenda a montar e gerenciar seu ambiente Docker Swarm de forma prática e organizada. Neste guia, você verá passo a passo como configurar o cluster
Clique aquiIniciando a Instalação do Portainer
Para manter tudo organizado e facilitar a gestão do projeto, vamos criar uma pasta no servidor destinada a armazenar os dados do Portainer.
A pasta portainer será a raiz do projeto. Dentro dela, criaremos a pasta dados, que terá uma função muito importante: é nela que o Portainer salvará todas as informações do seu ambiente, como configurações, usuários e histórico de containers.
Separar os dados dessa forma garante que, mesmo que algo aconteça com o Portainer ou com os containers, suas informações estarão seguras e organizadas, facilitando backups e manutenções futuras.
Meu caminho no servidor, o seu pode ser diferente:
/home/administrador/portainer/dados
mkdir portainer
cd portainer/
mkdir dados
Já dentro da pasta portainer, execute o comando abaixo, esse comando baixa o arquivo portainer-agent-stack.yml do site oficial do Portainer.
curl -L https://downloads.portainer.io/ce-lts/portainer-agent-stack.yml -o portainer-agent-stack.yml
Antes de executar, vamos ajustar o arquivo portainer-agent-stack.yml, para se adequar a nossa necessidade.
nano /home/administrador/portainer/portainer-agent-stack.yml
VERSÃO
Por padrão, o Portainer e o agente vêm configurados para usar a última versão disponível (latest). Porém, em ambientes de produção, não é recomendável utilizar o parâmetro latest. Isso acontece porque, a cada vez que a stack for atualizada, o Docker buscará automaticamente a versão mais recente da imagem. Se essa versão apresentar algum problema, seu ambiente pode ser afetado.
Para evitar esse tipo de risco, consultei o Docker Hub, verifiquei as versões disponíveis e selecionei a 2.36.0. Já utilizo essa versão em meu ambiente de produção e, até o momento, não encontrei nenhum problema.
VOLUMES
Adicionei também o nosso volume que criamos anteriormenente:
/home/administrador/portainer/dados
Essa pasta será o local onde o Portainer armazenará todas as suas informações, incluindo base de dados e outras configurações. Com isso, sempre que o Portainer for iniciado, ele irá buscar os arquivos nessa pasta e carregar os dados.
Sem a configuração de volumes, os dados não são persistidos. Isso significa que, a cada reinício do Portainer, ele começaria zerado, sem nenhuma informação anterior.
version: '3.2'
services:
# AGENTE PORTAINER
portainer-agent:
image: portainer/agent:2.36.0
volumes:
- /var/run/docker.sock:/var/run/docker.sock
- /var/lib/docker/volumes:/var/lib/docker/volumes
networks:
- rede-portainer-local
deploy:
mode: global
placement:
constraints: [node.platform.os == linux]
# SERVER PORTAINER
portainer-server:
image: portainer/portainer-ce:2.36.0
command: -H tcp://tasks.agent:9001 --tlsskipverify
ports:
- "8888:9443"
- "9000:9000"
- "8000:8000"
volumes:
- /home/administrador/portainer/dados:/data
environment:
- TZ=America/Recife
networks:
- rede-portainer-local
deploy:
mode: replicated
replicas: 1
placement:
constraints: [node.role == manager]
networks:
rede-portainer-local:
driver: overlay
Ajustes realizado vou descrever brevemente o que vai acontecer, temos dois serviços nesse arquivo (portainer-server e portainer-agent) coloquei assim pra melhor entender.
PORTAINER-AGENT
Esse serviço será replicado em cada servidor do Cluster, o Agent atua como um intermediário entre o Portainer (a interface web) e os nodes do cluster. Ele permite que o Portainer:
Se conecte de forma segura aos nodes do Docker.
Execute comandos e colete informações sobre containers, serviços, volumes, redes etc.
Gerencie múltiplos nodes em um Swarm sem precisar que o Portainer tenha acesso direto ao Docker de cada node.
Este serviço terá apenas uma réplica e, como mencionado anteriormente, será conectado aos Agents de cada node do cluster. Dessa forma, o Portainer Server consegue administrar todos os serviços e recursos do Docker em cada node, oferecendo uma visão centralizada e gerenciamento completo do ambiente.
Estando na pasta /portainer, onde está localizado o arquivo portainer-agent-stack.yml, podemos subir a Stack utilizando o seguinte comando:
docker stack deploy -c portainer-agent-stack.yml portainer
O nome portainer no final do comando acima, é o nome da stack que fica de sua preferência, você escolhe o que melhor se encaixa em seu ambiente e se tudo ocorreu normalmente, você poderá verificar as réplicas em execução utilizando o comando abaixo:
docker stack services portainer
Irá retornar algo semelhante a este abaixo, é possível ver que todas as replicas estão funcionando.
root@docker01:~# docker stack services portainer
ID NAME MODE REPLICAS IMAGE PORTS
swknuekqskrz portainer_portainer-agent global 5/5 portainer/agent:2.36.0
hm43nbvoeedc portainer_portainer-server replicated 1/1 portainer/portainer-ce:2.36.0
docker stack services portainer
Só pra relembrar o nome portainer em vermelho acima, é o nome da stack que eu dei quando usamos o comando docker stack deploy -c portainer-agent-stack.yml portainer o nome da stack fica a seu critério,.
Toda vez que precisar consultar informação da stack é necessário saber o nome da stack e pra saber quais stacks estão rodando em seu Swarm e seu respectivos nomes, use o comando abaixo:
docker stack ls
Será retornado algo parecido com a informação abaixo:
root@docker01:~# docker stack ls
NAME SERVICES
portainer 2
Com a stack funcionando, vamos acessar a interface web, precisamos saber em qual manager o portainer esta funcionando, pra isso vamos usar o comando abaixo:
docker stack ps portainer
root@docker01:~# docker stack ps portainer
ID NAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR PORTS
k2i42xh5a3jz portainer_portainer-agent.incoxqmp6a6kvn6lxjmpev6cb portainer/agent:2.36.0 docker05 Running Running 4 days ago
1i6d1lm2iwa8 portainer_portainer-agent.kf98zk7znyiesu08k08r31tcw portainer/agent:2.36.0 docker04 Running Running 4 days ago
w1g8r8b1kt5w portainer_portainer-agent.l8w71f18npkpyh9o2zf8qq7qi portainer/agent:2.36.0 docker01 Running Running 4 days ago
y5sso09ldba5 portainer_portainer-agent.t0kkphlsxmnlfh9wk9aqxcnur portainer/agent:2.36.0 docker03 Running Running 4 days ago
56obzngwyxto portainer_portainer-agent.wgcs0701qylmmlsi2wii76dh0 portainer/agent:2.36.0 docker02 Running Running 4 days ago
o8edy1rqbnmi portainer_portainer-server.1 portainer/portainer-ce:2.36.0 docker02 Running Running 4 days ago *:8000->8000/tcp,*:8000->8000/tcp,*:9000->9000/tcp,*:9000->9000/tcp,*:9443->9443/tcp,*:9443->9443/tcp
No retorno acima esta informando que o portainer-server esta rodando no servidor docker02. Para acessar a interface Web utilizo https://IP-Servidor:9443 a principio ele vai pedir um nome de usuário e senha
Após logar no Portainer, em muitos dos casos o ambiente será detectado automaticamente no Portainer:
É só selecionar o ambiente.
Pronto! Portainer instalado e pronto para utilização.
Profissional de TI com mais de 10 anos de experiência em infraestrutura, Linux, virtualização e contêineres. Atua com Docker, Docker Swarm e implantação de soluções VoIP, sempre focado em otimizar ambientes e compartilhar conhecimento com a comunidade.
