Portainer com Docker 29 - Guia de Instalação e Correção

Problema

Ao usar Docker 29.0.0+ com Portainer CE 2.33.x, você pode encontrar o erro:

Failed loading environment

Causa: Docker 29 aumentou a versão mínima da API para 1.44, mas o Portainer ainda tenta usar a API 1.24/1.41, resultando em incompatibilidade.

Pré-requisitos

Docker 29.0.0+ instalado
Acesso sudo/root
Porta 9001 (HTTP) e 9443 (HTTPS) disponíveis

Solução Completa

1. Instalar/Atualizar Portainer

Se você já tem Portainer instalado, remova primeiro:

docker stop portainer 2>/dev/null
docker rm portainer 2>/dev/null

Opcional: Se quiser começar do zero (apaga dados antigos):

docker volume rm portainer_data 2>/dev/null

Instale a versão mais recente do Portainer:

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

2. Aplicar Workaround para Docker 29

Este é o passo CRUCIAL para fazer o Portainer funcionar com Docker 29.

Método 1: Comando direto (recomendado)

echo '{
  "min-api-version": "1.24"
}' | sudo tee /etc/docker/daemon.json

Método 2: Editar manualmente

sudo nano /etc/docker/daemon.json

Adicione este conteúdo:

{
  "min-api-version": "1.24"
}

Salve e feche (Ctrl+O, Enter, Ctrl+X).

3. Reiniciar Docker e Portainer

sudo systemctl restart docker
docker restart portainer

Ou use este comando completo:

echo '{
  "min-api-version": "1.24"
}' | sudo tee /etc/docker/daemon.json && \
sudo systemctl restart docker && \
docker restart portainer

4. Verificar se está funcionando

# Verificar versões
docker version --format 'Docker: {{.Server.Version}} | API: {{.Server.APIVersion}}'
docker logs portainer --tail 10

# Status do Portainer
docker ps | grep portainer

5. Acessar o Portainer

HTTP: http://localhost:9001
HTTPS: https://localhost:9443

Na primeira vez:

Crie um usuário admin (username e senha)
Após login, o environment "local" já estará configurado automaticamente
Clique nele para gerenciar seus containers

Troubleshooting

Erro: Portainer não inicia ou restart dá timeout

# Forçar parada e reiniciar
docker kill portainer
docker start portainer

# Ou recriar completamente
docker kill portainer && docker rm portainer
docker run -d \
  --name portainer \
  --restart=always \
  -p 9001:9000 \
  -p 9443:9443 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v portainer_data:/data \
  portainer/portainer-ce:latest

Erro: "Failed loading environment" persiste

Verifique se o daemon.json está correto:

cat /etc/docker/daemon.json

Verifique se o Docker reiniciou com sucesso:

sudo systemctl status docker

Verifique os logs do Portainer:

docker logs portainer --tail 50

Se necessário, remova tudo e comece do zero:

# Parar e remover Portainer
docker stop portainer && docker rm portainer

# Remover volume de dados (ATENÇÃO: apaga configurações)
docker volume rm portainer_data

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

Verificar permissões do Docker socket

ls -la /var/run/docker.sock
# Deve mostrar: srw-rw---- 1 root docker

# Se necessário, adicionar usuário ao grupo docker
sudo usermod -aG docker $USER
newgrp docker

Informações Técnicas

O que o workaround faz?

A configuração "min-api-version": "1.24" no daemon.json força o Docker 29 a aceitar clientes que usam versões antigas da API (como o Portainer).

Sem isso:

Docker 29 requer API mínima: 1.44
Portainer tenta usar: 1.24 ou 1.41
Resultado: Incompatibilidade

Com isso:

Docker 29 aceita API: 1.24 ou superior
Portainer consegue conectar: ✓

Quando a correção oficial chegará?

Segundo a equipe do Portainer, o suporte oficial ao Docker 29 está previsto para:

Portainer 2.36 STS (próximo lançamento)

Até lá, o workaround é a solução recomendada.

Versões testadas

✓ Docker: 29.0.0, 29.0.1
✓ Portainer CE: 2.33.3, 2.33.4
✓ Sistemas: Ubuntu 24.04, Debian 12/13, outros Linux

Comandos Úteis

Verificar versões

# Docker
docker --version
docker version --format 'API: {{.Server.APIVersion}}'

# Portainer (via logs)
docker logs portainer 2>&1 | grep "version="

Gerenciar Portainer

# Ver logs
docker logs portainer -f

# Parar
docker stop portainer

# Iniciar
docker start portainer

# Reiniciar (se travar, use kill)
docker restart portainer
# ou
docker kill portainer && docker start portainer

# Remover
docker stop portainer && docker rm portainer

# Remover volume (apaga dados)
docker volume rm portainer_data

Backup/Restore

# Backup do volume de dados
docker run --rm -v portainer_data:/data -v $(pwd):/backup ubuntu tar czf /backup/portainer_backup.tar.gz /data

# Restore
docker run --rm -v portainer_data:/data -v $(pwd):/backup ubuntu tar xzf /backup/portainer_backup.tar.gz -C /

Script de Instalação Completo

Salve este script como install-portainer.sh:

#!/bin/bash
set -e

echo "=== Instalação Portainer + Workaround Docker 29 ==="

# 1. Remover instalação antiga (se existir)
echo "1. Removendo Portainer antigo..."
docker stop portainer 2>/dev/null || true
docker rm portainer 2>/dev/null || true

# 2. Configurar daemon.json
echo "2. Configurando Docker daemon..."
echo '{
  "min-api-version": "1.24"
}' | sudo tee /etc/docker/daemon.json > /dev/null

# 3. Reiniciar Docker
echo "3. Reiniciando Docker..."
sudo systemctl restart docker
sleep 3

# 4. Instalar Portainer
echo "4. Instalando Portainer..."
docker run -d \
  --name portainer \
  --restart=always \
  -p 9001:9000 \
  -p 9443:9443 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v portainer_data:/data \
  portainer/portainer-ce:latest

# 5. Verificar
echo "5. Verificando instalação..."
sleep 5
docker ps | grep portainer

echo ""
echo "=== Instalação Concluída! ==="
echo "Acesse: http://localhost:9001"
echo ""
docker logs portainer --tail 5

Torne executável e execute:

chmod +x install-portainer.sh
./install-portainer.sh

Referências

Notas Importantes

⚠️ Este é um workaround temporário. A solução oficial será lançada no Portainer 2.36 STS.

⚠️ Sempre faça backup dos volumes do Portainer antes de grandes mudanças:

docker run --rm -v portainer_data:/data -v $(pwd):/backup ubuntu tar czf /backup/portainer_backup.tar.gz /data

✅ Após aplicar o workaround, o Portainer funcionará normalmente com Docker 29.

Última atualização: 2025-11-26 Testado em: Docker 29.0.1 + Portainer CE 2.33.4

rg3915/README.md

Select an option

No results found