Portainer¶

O Portainer fornece uma interface web para administrar containers, imagens, volumes, redes e stacks Docker.

Nesta VPS, ele é uma ferramenta administrativa não essencial e pode permanecer desligado durante o modo econômico.

Informações desta VPS¶

Item	Valor
Stack	`/opt/stacks/infra/compose.yml`
Serviço Compose	`portainer`
Container	`infra-portainer-1`
Imagem configurada	`portainer/portainer-ce:latest`
Versão registrada	`2.33.5`
Domínio	`https://portainer.cloud.hometecseg.com`
Porta interna	`9000`
Rede Docker	`proxy`
Volume	`infra_portainer-data`
Diretório no container	`/data`
Docker Socket	`/var/run/docker.sock`
Operação contínua	Não obrigatória

Modo econômico

O Portainer pode aparecer como parado porque é desligado propositalmente pelo script de modo econômico da VPS. Isso não significa necessariamente falha.

Estado atual¶

Ver o estado do Portainer¶

docker compose -f /opt/stacks/infra/compose.yml ps -a portainer

Ver somente containers em execução¶

docker ps --filter name=infra-portainer-1

Ver containers ativos ou parados¶

docker ps -a --filter name=infra-portainer-1

Ver o estado detalhado¶

docker inspect infra-portainer-1 \
  --format 'Status={{.State.Status}} ExitCode={{.State.ExitCode}} FinishedAt={{.State.FinishedAt}} OOMKilled={{.State.OOMKilled}}'

Iniciar e parar¶

Iniciar o Portainer¶

docker compose -f /opt/stacks/infra/compose.yml start portainer

Caso o container ainda não exista:

docker compose -f /opt/stacks/infra/compose.yml up -d portainer

Parar o Portainer¶

docker compose -f /opt/stacks/infra/compose.yml stop portainer

Reiniciar o Portainer¶

docker compose -f /opt/stacks/infra/compose.yml restart portainer

Recriar o container¶

docker compose -f /opt/stacks/infra/compose.yml up -d --force-recreate portainer

Confirmar o estado após iniciar¶

docker compose -f /opt/stacks/infra/compose.yml ps portainer

Acesso¶

Endereço:

https://portainer.cloud.hometecseg.com

Testar o domínio¶

curl -I https://portainer.cloud.hometecseg.com

Verificar o DNS¶

getent hosts portainer.cloud.hometecseg.com

Ver detalhes da conexão HTTPS¶

curl -v https://portainer.cloud.hometecseg.com

Serviço desligado

O domínio ficará indisponível enquanto o Portainer estiver parado pelo modo econômico.

Logs¶

Ver os últimos 100 registros¶

docker logs infra-portainer-1 --tail 100

Acompanhar os logs em tempo real¶

docker logs -f infra-portainer-1

Procurar erros¶

docker logs infra-portainer-1 2>&1 | grep -Ei "error|fatal|panic"

Procurar avisos¶

docker logs infra-portainer-1 2>&1 | grep -i warning

Ver os registros da última inicialização¶

docker logs infra-portainer-1 \
  --since "$(docker inspect infra-portainer-1 --format '{{.State.StartedAt}}')"

Versão¶

Ver a versão registrada nos logs¶

docker logs infra-portainer-1 2>&1 \
  | grep "starting Portainer" \
  | tail -1

Mostrar somente o número da versão¶

docker logs infra-portainer-1 2>&1 \
  | grep "starting Portainer" \
  | tail -1 \
  | grep -oE 'version=[^ ]+'

Ver a imagem configurada no Compose¶

grep -n "portainer/portainer-ce" /opt/stacks/infra/compose.yml

Ver a imagem associada ao container¶

docker inspect infra-portainer-1 --format '{{.Config.Image}}'

Ver o identificador da imagem local¶

docker inspect infra-portainer-1 --format '{{.Image}}'

Versões disponíveis¶

A instalação atual utiliza:

portainer/portainer-ce:latest

Para servidores de produção, é preferível usar a linha LTS:

portainer/portainer-ce:lts

A sigla LTS significa Long-Term Support, ou suporte de longo prazo. Essa linha prioriza estabilidade e manutenção em vez de receber imediatamente todas as novidades.

Estado registrado ao criar esta documentação:

Canal	Versão
Versão instalada registrada	`2.33.5`
LTS disponível	`2.39.4`
STS disponível	`2.43.0`

O canal STS recebe funcionalidades mais recentes. Para esta VPS, a linha LTS é a opção mais prudente.

Valores temporais

As versões disponíveis mudam com o tempo. Consulte sempre a página oficial de releases antes de atualizar.

Verificar atualização disponível¶

Baixar os metadados da imagem LTS¶

docker pull portainer/portainer-ce:lts

Esse comando baixa a imagem, mas não recria o container.

Ver o identificador da imagem LTS baixada¶

docker image inspect portainer/portainer-ce:lts \
  --format '{{.Id}}'

Ver o identificador da imagem utilizada pelo container¶

docker inspect infra-portainer-1 --format '{{.Image}}'

Se os identificadores forem diferentes, o container ainda utiliza uma imagem anterior.

Comparar automaticamente¶

CONTAINER_IMAGE="$(docker inspect infra-portainer-1 --format '{{.Image}}')" &&
LATEST_IMAGE="$(docker image inspect portainer/portainer-ce:lts --format '{{.Id}}')" &&
if [ "$CONTAINER_IMAGE" = "$LATEST_IMAGE" ]; then
  echo "Portainer já utiliza a imagem LTS baixada."
else
  echo "Existe uma imagem LTS diferente da usada pelo container."
fi

Imagem diferente não garante versão maior

A comparação detecta imagens diferentes. Ela não analisa semanticamente os números de versão. Imagens podem mudar por reconstruções de segurança sem alterar o número principal.

Preparação para atualização¶

Criar diretório de backup¶

mkdir -p /opt/backups/portainer

Criar backup do Compose¶

cp /opt/stacks/infra/compose.yml \
  /opt/backups/portainer/compose-$(date +%Y%m%d-%H%M%S).yml

Criar backup do arquivo de ambiente¶

cp /opt/stacks/infra/.env \
  /opt/backups/portainer/env-$(date +%Y%m%d-%H%M%S).bak

Verificar o volume¶

docker volume inspect infra_portainer-data

Ver o espaço utilizado¶

du -sh /var/lib/docker/volumes/infra_portainer-data/_data

Backup dos dados¶

Criar backup compactado do volume¶

docker run --rm \
  -v infra_portainer-data:/source:ro \
  -v /opt/backups/portainer:/backup \
  alpine \
  tar -czf "/backup/portainer-data-$(date +%Y%m%d-%H%M%S).tar.gz" \
  -C /source .

Listar os backups¶

ls -lh /opt/backups/portainer

Verificar o conteúdo do backup¶

tar -tzf /opt/backups/portainer/NOME_DO_BACKUP.tar.gz | head

Atualizar para LTS¶

Criar backup antes da atualização¶

docker run --rm \
  -v infra_portainer-data:/source:ro \
  -v /opt/backups/portainer:/backup \
  alpine \
  tar -czf "/backup/portainer-data-pre-update-$(date +%Y%m%d-%H%M%S).tar.gz" \
  -C /source .

Alterar a imagem no Compose¶

No arquivo:

/opt/stacks/infra/compose.yml

Substituir:

image: portainer/portainer-ce:latest

por:

image: portainer/portainer-ce:lts

Validar o Compose¶

docker compose -f /opt/stacks/infra/compose.yml config

Baixar a imagem LTS¶

docker compose -f /opt/stacks/infra/compose.yml pull portainer

Recriar somente o Portainer¶

docker compose -f /opt/stacks/infra/compose.yml up -d portainer

Verificar o estado¶

docker compose -f /opt/stacks/infra/compose.yml ps portainer

Verificar os logs¶

docker logs infra-portainer-1 --tail 100

Confirmar a versão¶

docker logs infra-portainer-1 2>&1 \
  | grep "starting Portainer" \
  | tail -1

Testar o domínio¶

curl -I https://portainer.cloud.hometecseg.com

Atualização pelo script¶

Existe um script dedicado:

/usr/local/bin/update_portainer.sh

Ele será analisado e documentado posteriormente na página de scripts.

Antes de utilizá-lo:

sed -n '1,240p' /usr/local/bin/update_portainer.sh

Para verificar permissões:

ls -l /usr/local/bin/update_portainer.sh

Não executar sem revisão

O script deve ser revisado antes de ser chamado pela documentação. Ainda precisamos confirmar se ele cria backup, usa latest ou lts, valida o container e oferece rollback.

Volume persistente¶

Ver as montagens¶

docker inspect infra-portainer-1 \
  --format '{{range .Mounts}}{{println .Type "|" .Name "|" .Source "|" .Destination}}{{end}}'

Inspecionar o volume¶

docker volume inspect infra_portainer-data

Ver os arquivos persistentes¶

ls -lah /var/lib/docker/volumes/infra_portainer-data/_data

Ver o banco interno¶

ls -lh /var/lib/docker/volumes/infra_portainer-data/_data/portainer.db

Não editar diretamente

Não edite manualmente o arquivo portainer.db. Ele é controlado pelo Portainer e utiliza o formato BoltDB.

Docker Socket¶

O Portainer possui acesso a:

/var/run/docker.sock

Essa montagem permite administrar o Docker da VPS.

Confirmar a montagem¶

docker inspect infra-portainer-1 \
  --format '{{range .Mounts}}{{println .Source "->" .Destination}}{{end}}'

Acesso privilegiado

Um container com acesso ao Docker Socket pode controlar containers, volumes, redes e, em muitos cenários, o próprio host. O painel deve possuir senha forte e não deve ficar exposto sem proteção.

Traefik¶

Ver as labels¶

docker inspect infra-portainer-1 \
  --format '{{json .Config.Labels}}'

Verificar a rede proxy¶

docker network inspect proxy

Confirmar as redes do container¶

docker inspect infra-portainer-1 \
  --format '{{json .NetworkSettings.Networks}}'

Ver logs do Traefik¶

docker logs reverse-proxy-traefik-1 --tail 100

Troubleshooting¶

Portainer aparece como parado¶

Verificar:

docker compose -f /opt/stacks/infra/compose.yml ps -a portainer

Se ele tiver sido parado pelo modo econômico, iniciar com:

docker compose -f /opt/stacks/infra/compose.yml start portainer

Caso o container não exista:

docker compose -f /opt/stacks/infra/compose.yml up -d portainer

Portainer encerra após iniciar¶

Verificar:

docker logs infra-portainer-1 --tail 200

docker inspect infra-portainer-1 \
  --format 'ExitCode={{.State.ExitCode}} Error={{printf "%q" .State.Error}} OOMKilled={{.State.OOMKilled}}'

docker compose -f /opt/stacks/infra/compose.yml config

Erro 404¶

Verificar as labels:

docker inspect infra-portainer-1 \
  --format '{{json .Config.Labels}}'

Verificar o domínio:

getent hosts portainer.cloud.hometecseg.com

Verificar o Traefik:

docker logs reverse-proxy-traefik-1 --tail 100

Erro 502 ou Gateway Timeout¶

Verificar se o Portainer está ativo:

docker compose -f /opt/stacks/infra/compose.yml ps portainer

Verificar a rede:

docker network inspect proxy

Verificar a porta configurada:

docker inspect infra-portainer-1 \
  --format '{{json .Config.Labels}}' \
  | grep loadbalancer

A porta esperada nesta VPS é:

Ambiente Docker aparece desconectado¶

Verificar o Docker Socket:

ls -l /var/run/docker.sock

Verificar a montagem:

docker inspect infra-portainer-1 \
  --format '{{range .Mounts}}{{println .Source "->" .Destination}}{{end}}'

Verificar os logs:

docker logs infra-portainer-1 --tail 200

Senha administrativa esquecida¶

Não apague o volume.

Primeiro, crie um backup:

docker run --rm \
  -v infra_portainer-data:/source:ro \
  -v /opt/backups/portainer:/backup \
  alpine \
  tar -czf "/backup/portainer-data-before-password-reset-$(date +%Y%m%d-%H%M%S).tar.gz" \
  -C /source .

O procedimento de redefinição de senha deve ser conferido na documentação oficial correspondente à versão instalada.

Boas práticas¶

Manter o Portainer desligado quando não for necessário.
Preferir a imagem portainer/portainer-ce:lts.
Fazer backup do volume antes das atualizações.
Não remover o volume infra_portainer-data.
Não publicar diretamente as portas 9000 ou 9443.
Utilizar apenas o Traefik para acesso externo.
Usar senha administrativa forte.
Verificar logs após toda atualização.
Revisar o script de atualização antes de executá-lo.
Não usar docker compose down -v.