NexTool Solutions

Atualizar o GLPI no Docker parece trivial - trocar a etiqueta da imagem e subir o contentor - mas é justamente essa aparente simplicidade que gera indisponibilidade não planeada. Na sustentação de ambientes de clientes, a maioria dos incidentes de atualização não vem da migração da base de dados em si, mas de plugins incompatíveis, do PHP embutido na imagem nova ou de um volume mal mapeado que faz o GLPI perder a configuração de base de dados. Este guia consolida o procedimento que aplicamos em produção, com os pontos onde as coisas realmente quebram.

Antes de mexer em qualquer contentor: o inventário de compatibilidade

Uma atualização de GLPI não é só a imagem. São três camadas que precisam de subir juntas: o núcleo, os plugins e o esquema da base de dados. O erro clássico é atualizar a imagem e descobrir, com o site em baixo, que um plugin crítico (por exemplo o de inventário nativo, um SSO ou um campo personalizado) não tem versão para o novo núcleo. Levante isto primeiro:

• Versões exatas de origem e destino - salto menor (10.0.15 para 10.0.18) é seguro; salto maior (10.x para 11.x) muda o requisito de PHP e pode aposentar plugins.
• Matriz de plugins - para cada plugin instalado, confirmar que existe versão compatível com o destino. Plugin sem versão compatível é uma decisão de negócio (desativar, substituir ou adiar a atualização), nunca uma surpresa às 2h da manhã.
• PHP embutido na imagem - a imagem oficial já traz o PHP certo, mas se usar imagem própria (Alpine + php-fpm), o GLPI 11 exige PHP 8.2+. Um núcleo novo sobre PHP antigo dá ecrã em branco sem registo claro.
• Espaço em disco - o dump e o tar de volumes podem duplicar temporariamente o uso. Verifique antes, não durante.

Matriz de decisão: menor, maior ou saltar versões

O tipo de salto define o procedimento. Esta é a matriz que usamos para dimensionar janela e risco:

O erro comum aqui é achar que saltar versões poupa tempo. O GLPI não garante migração de esquema saltando um maior inteiro; a rotina db:update espera a estrutura da versão imediatamente anterior. Saltar 9.5 direto para 11 costuma travar a migração a meio, com a base de dados em estado inconsistente - e aí o rollback deixa de ser opcional.

Passo a passo da atualização

1. Cópia de segurança consistente (base de dados + volumes)

Cópia de segurança não é o dump sozinho. É o dump da base de dados mais o tar dos volumes de ficheiros (carregamentos, documentos, cache de plugins). Os dois têm de ser do mesmo instante - por isso paramos a aplicação primeiro, mantendo só a base de dados de pé para o dump:

# Para a app, mantém a base de dados de pé
docker compose stop glpi-app

# Dump da base de dados (utilizador dedicado, palavra-passe via variável de ambiente)
docker exec glpi-db sh -c 'mysqldump --single-transaction \
  -u glpi -p"${MYSQL_PASSWORD}" glpi' | gzip > /backup/pre-update-$(date +%F).sql.gz

# Tar dos volumes de ficheiros do GLPI
tar -czf /backup/pre-update-files-$(date +%F).tar.gz \
  /var/lib/docker/volumes/glpi_files/_data

O --single-transaction garante um dump coerente sem bloquear as tabelas InnoDB. E jamais coloque a palavra-passe literal na linha de comandos: fica exposta no histórico da shell e no docker inspect.

2. Fixar a versão de destino no compose

Nunca use a etiqueta latest em produção. Move o alvo sem aviso e impede um rollback determinístico. Fixe a versão exata:

# docker-compose.yml
services:
  glpi-app:
    # De:
    image: glpi/glpi:10.0.18
    # Para (versão exata de destino, nunca :latest):
    image: glpi/glpi:11.0.1
    volumes:
      - glpi_files:/var/glpi/files
      - glpi_config:/var/glpi/config   # config_db.php mora aqui - NÃO perder

3. Subir a nova imagem

docker compose pull glpi-app
docker compose up -d glpi-app

4. Correr a migração de esquema

O comando de migração mudou de nome entre gerações do GLPI. Confirme qual o binário disponível antes de correr às cegas:

# GLPI 10/11 (consola Symfony):
docker exec -u www-data glpi-app php bin/console db:update --no-interaction

# GLPI mais antigo (10.0 inicial) usava:
# docker exec -u www-data glpi-app php bin/console glpi:database:update --no-interaction

Corra sempre como o utilizador do servidor web (www-data ou apache), nunca como root. Correr a migração como root cria ficheiros de cache com dono errado, e o GLPI passa a dar erro de permissão depois - um falso "quebrou na atualização" que é só propriedade de ficheiros.

5. Limpar cache e validar

docker exec -u www-data glpi-app php bin/console cache:clear

• Aceda à interface e confirme a versão em Configuração > Geral.
• Corra o diagnóstico interno em Configuração > Verificações (PHP, extensões e permissões).
• Confirme que os plugins críticos aparecem como ativos, não como "precisa de atualizar".
• Teste um fluxo real: abrir um pedido, anexar um documento, despoletar uma notificação.

O que aprendemos a operar isto para clientes

Na sustentação, o incidente que mais se repete não é a migração falhar - é a migração parecer ter corrido bem e o GLPI subir com a base de dados predefinida vazia. A causa é quase sempre a mesma: o volume que guarda o config/config_db.php não foi mapeado, ou foi mapeado para um caminho diferente na versão nova. O GLPI não encontra a configuração de base de dados, assume que é uma instalação limpa e mostra o assistente de instalação. Quem está com pressa carrega em "instalar" e cria uma base nova por cima - agora, além da indisponibilidade, há risco de perda de dados. Por isso, na nossa checklist, a primeira validação pós-arranque não é a versão: é o docker exec glpi-app cat /var/glpi/config/config_db.php devolver a configuração real do cliente. Se aparecer o assistente, paramos tudo antes de qualquer clique e revemos o mapeamento do volume - nunca seguimos pela interface.

O segundo padrão é a cache do OPcache a servir código antigo depois da atualização. A imagem trocou, o código no disco é novo, mas o php-fpm ainda tem a versão antiga compilada em memória. Sintoma: erros de método inexistente ou versão do núcleo que não bate certo com a imagem. Recriar o contentor (e não apenas reiniciar) resolve, porque o processo do php-fpm é reinicializado do zero.

Plano de rollback (ensaiado, não improvisado)

Um rollback só é fiável se foi pensado antes. Com o dump e o tar do passo 1, o retorno é determinístico:

# Deita abaixo a versão nova
docker compose down

# Restaura a base de dados a partir do dump
gunzip < /backup/pre-update-2026-07-02.sql.gz \
  | docker exec -i glpi-db sh -c 'mysql -u glpi -p"${MYSQL_PASSWORD}" glpi'

# Reverte a etiqueta da imagem no docker-compose.yml para a versão anterior
# (ex.: glpi/glpi:11.0.1 de volta para glpi/glpi:10.0.18)

docker compose up -d

Ponto crítico do rollback: o esquema. Depois de o db:update ter alterado a estrutura, a base de dados já não é compatível com a imagem antiga. Por isso o rollback tem de restaurar o dump - não basta voltar a etiqueta. Restaurar só a imagem, com o esquema já migrado, deixa o GLPI antigo a ler tabelas de estrutura futura, o que gera erros silenciosos e difíceis de rastrear.

Fazer isto sem indisponibilidade não planeada

Se o ambiente é crítico, a janela precisa de ser ensaiada em homologação com um clone da base de dados de produção. É aí que se descobre, sem pressão, se um plugin quebra ou se a migração demora mais que a janela combinada. Atualizar direto em produção sem esse ensaio é apostar a disponibilidade do cliente na sorte.

Se a sua equipa não tem janela para ensaiar cada atualização, ou já apanhou de uma atualização que virou madrugada, a NexTool trata da sustentação e das atualizações do seu GLPI com rollback ensaiado e janela combinada. Fale connosco sobre suporte e sustentação de GLPI.

Este conteúdo foi produzido com auxílio de inteligência artificial e revisto pela equipa Nextool Solutions.