NexTool Solutions

Atualizámos duas vezes uma cópia de um GLPI 11.0.11 para o 12.0.0: em Docker com a imagem oficial e em Debian 13 com o pacote .tgz. A migração da base de dados demorou cerca de 5 segundos nos dois casos. O trabalho veio antes e depois: o MariaDB 10.6 foi recusado, os plugins ficaram suspensos, as categorias da base de conhecimento passaram a artigos que técnicos e utilizadores não conseguem abrir e o webhook deixou de enviar, por dois motivos diferentes. Este guia traz o passo a passo dos dois caminhos e a correção de cada problema, pela ordem em que surgiram.

Ainda a decidir se é altura de atualizar? Leia primeiro O GLPI 12 saiu: o que muda, requisitos e quando atualizar.

O que testámos

Montámos um GLPI 11.0.11 descartável com dados fictícios da Acme: 120 tickets com seguimentos e 40 tarefas, um SLA, 9 artigos da base de conhecimento em 4 categorias com permissões diferentes, um webhook para um servidor interno e três plugins da comunidade (Fields, Tag e Data Injection), com dados. Fizemos a cópia de segurança e atualizámos para o 12.0.0. Depois restaurámos a mesma cópia num Debian 13 e repetimos a atualização com o pacote .tgz.

Antes de começar: requisitos

Dois pormenores que o teste revelou:

• O PHP 8.2 não dá um aviso, dá um erro de sintaxe. A consola do GLPI 12 nem chega a verificar os requisitos: para com um "Parse error" num ficheiro do próprio GLPI. O Debian 12 e o Ubuntu 22.04 trazem PHP 8.2 ou mais antigo. O Debian 13 (PHP 8.4) e o Ubuntu 24.04 (PHP 8.3) cumprem com os pacotes de origem. A imagem Docker oficial já traz PHP 8.5.
• Verifique a base de dados antes de tudo. Execute php bin/console system:check_requirements com o código novo apontado para a sua base. No nosso MariaDB 10.6 a resposta foi direta: versão não suportada, mínimo 10.11.

Passo 0: cópia de segurança (base de dados, ficheiros e a chave)

Faça três cópias antes de mexer em qualquer coisa: a base de dados, a pasta de ficheiros e a pasta de configuração. A pasta de configuração tem o glpicrypt.key. Sem ele, as palavras-passe guardadas pelo GLPI (recolha de e-mail, LDAP, proxy, segredos de webhook) deixam de abrir.

mariadb-dump --single-transaction --routines -u root -p glpi | gzip > glpi11-$(date +%F).sql.gz
tar czf glpi11-arquivos-$(date +%F).tgz /etc/glpi /var/lib/glpi/files /var/www/glpi/marketplace

No Docker com a imagem oficial, tudo fica no volume montado em /var/glpi (config, files, marketplace e logs): copie o volume inteiro. No nosso teste, o dump demorou 5 segundos e a cópia do volume 8,5.

Caminho 1: Docker com a imagem oficial

A imagem oficial (glpi/glpi) atualiza a base de dados sozinha quando arranca com uma versão nova. Basta trocar a tag e arrancar o contentor: não há confirmação. Por isso a cópia de segurança vem antes da troca de tag, nunca depois. Se preferir fazer a atualização à mão, arranque com GLPI_SKIP_AUTOUPDATE=true e use o comando do caminho 2.

1. Atualize o MariaDB, se for preciso. Com o MariaDB 10.6, o contentor do GLPI 12 terminou com o código 128. O log avisou que faltavam requisitos e, logo a seguir, escreveu uma frase que assusta: "GLPI is not installed... Starting installation". Não instalou nada. A base de dados ficou intacta, na versão 11.0.11, com os 120 tickets. Apenas não passou na verificação de requisitos. A passagem do MariaDB 10.6 para o 10.11 demorou 22 segundos com a variável de atualização automática da imagem do MariaDB. Arranque primeiro só a base de dados (docker compose up -d db) e confira o log antes de continuar:

services:
  db:
    image: mariadb:10.11          # era 10.6
    environment:
      MARIADB_AUTO_UPGRADE: "1"   # executa o mariadb-upgrade ao arrancar
  glpi:
    image: glpi/glpi:12.0.0       # era 11.0.11 (passo 2)
    volumes:
      - glpi-data:/var/glpi

2. Troque a tag e arranque. docker compose up -d. O log mostra "GLPI is installed, and auto-update is enabled. Starting update..." e, a seguir, a mensagem de boas-vindas. No teste foram 17 segundos entre o up e a mensagem de boas-vindas no log.

3. Confirme. docker compose exec glpi bin/console db:check deve responder "Database schema is OK".

Caminho 2: Linux com o pacote .tgz

Os comandos abaixo seguem a estrutura do nosso guia de instalação do GLPI 11 em Debian e Ubuntu: código em /var/www/glpi, configuração em /etc/glpi e ficheiros em /var/lib/glpi/files.

cd /var/www/glpi && sudo -u www-data php bin/console maintenance:enable
cd /var/www && mv glpi glpi-11-antigo
wget https://github.com/glpi-project/glpi/releases/download/12.0.0/glpi-12.0.0.tgz
tar xzf glpi-12.0.0.tgz
cp glpi-11-antigo/inc/downstream.php glpi/inc/                  # se existir
cp glpi-11-antigo/config/local_define.php glpi/config/ 2>/dev/null  # se existir
cp -a glpi-11-antigo/marketplace/. glpi/marketplace/
chown -R www-data:www-data glpi
cd glpi
sudo -u www-data php bin/console system:check_requirements
sudo -u www-data php bin/console database:update
sudo -u www-data php bin/console maintenance:disable

O ficheiro de que ninguém se lembra: inc/downstream.php. É ele que diz ao GLPI que a configuração está em /etc/glpi. Vive dentro da pasta do código, por isso desaparece quando troca a pasta. No teste, sem ele, o database:update respondeu "Unable to connect to database". A mensagem não diz o motivo real: o GLPI procurou a configuração no sítio errado. Com o ficheiro copiado de volta, a atualização correu de imediato. O mesmo vale para config/local_define.php, se o usar.

Se o seu GLPI guarda config e files dentro de /var/www/glpi, copie também config/ e files/ da pasta antiga. Foi assim no Debian 13 (PHP 8.4): a migração demorou 5 segundos e o db:check saiu limpo.

Se a atualização da base de dados falhar

No fórum do GLPI surgiu, a 3 de novembro, uma atualização do 11.0.8 para o 12.0.1 em Debian 13 que encravou: os ficheiros foram copiados, dono e permissões ajustados, e o maintenance:disable deu erro e a atualização da base de dados falhou. Não reproduzimos este caso. Uma resposta no tópico apontou uma causa provável, e o código da migração confirma que é possível: no 11, a tabela que liga artigos a categorias da base de conhecimento aceita o mesmo par artigo/categoria repetido; a tabela que a substitui no 12 não aceita. Um vínculo duplicado basta para parar a migração. Reponha a cópia de segurança do 11 (a migração pode ter parado a meio) e procure duplicados:

SELECT knowbaseitems_id, knowbaseitemcategories_id, COUNT(*) AS n
FROM glpi_knowbaseitems_knowbaseitemcategories
GROUP BY knowbaseitems_id, knowbaseitemcategories_id
HAVING n > 1;

Se aparecer alguma linha, apague as cópias e mantenha um vínculo por par. O artigo continua na categoria:

DELETE l1 FROM glpi_knowbaseitems_knowbaseitemcategories l1
JOIN glpi_knowbaseitems_knowbaseitemcategories l2
  ON l1.knowbaseitems_id = l2.knowbaseitems_id
 AND l1.knowbaseitemcategories_id = l2.knowbaseitemcategories_id
 AND l1.id > l2.id;

Se a consulta vier vazia, a causa é outra. Confirme que a pasta de ficheiros e a de configuração (no nosso layout, /var/lib/glpi/files e /etc/glpi) pertencem ao www-data, corra o system:check_requirements e leia o php-errors.log na pasta _log dos ficheiros e o registo de erros do servidor web. Corra o database:update pela linha de comandos, que mostra o erro no ecrã, e só depois o maintenance:disable.

Depois da migração: o que avariou e como resolver

1. Os plugins ficam suspensos (e o comando de listagem não o diz)

Depois da atualização, o GLPI 12 suspende a execução de todos os plugins. O plugin:list continuou a mostrar os três como "Enabled". Mas a configuração plugins_execution_mode estava em "suspended_by_update", e nenhum plugin corria. Para os libertar:

php bin/console plugin:resume_execution

Ao libertá-los, o GLPI verificou as versões e desativou os três ("Installed / not activated"). As versões para o 11 aceitam no máximo o GLPI 11.0.99, e as versões para o 12 exigem no mínimo o 12.0.0. Ou seja: não é possível atualizar estes plugins antes do GLPI. Primeiro o GLPI, depois os plugins:

Para cada um: substitua a pasta em marketplace/ pela versão nova e execute plugin:install e plugin:activate. Os dados mantiveram-se: os 5 valores do campo "Centro de custo" do Fields e as 10 etiquetas do Tag continuaram lá. Antes de marcar a data, confirme que todos os seus plugins já têm versão para o 12 (como escolher plugins sem bloquear o upgrade).

2. As categorias da base de conhecimento passam a artigos sem visibilidade

O GLPI 12 deixou de ter categorias na base de conhecimento: as 4 categorias passaram a 4 artigos "pai", e foi criado um artigo raiz ("Home") acima deles. Os 9 artigos mantiveram as permissões que tinham. Mas os 4 artigos que eram categorias ficaram sem nenhuma regra de visibilidade. Testámos pela API com um técnico e um utilizador do Self-Service: ambos receberam erro 403 ao abrir "Procedimentos", "Rede", "Wi-Fi" e "FAQ do utilizador". Cada um continuou a abrir apenas os artigos que já via antes.

Correção: abra cada antiga categoria e dê-lhe o público que a pasta tinha (entidade, perfil ou grupo). No 12, um artigo herda a visibilidade dos artigos acima dele. No teste, abrir a antiga categoria "FAQ do utilizador" à entidade Acme fez com que o técnico passasse a abrir a pasta e os dois artigos dentro dela, que antes davam 403. Para o utilizador do Self-Service há um passo extra: só vê artigos marcados como FAQ, e as antigas categorias chegam sem essa marca. Com visibilidade e a marca de FAQ, a pasta passou a aparecer também para ele. Faça isto antes de abrir o sistema aos utilizadores.

3. O webhook parou: método "post" em minúsculas

O webhook criado no GLPI 11 entrou na fila e falhou. O log webhook.log mostrou a causa: Invalid HTTP method "post", only uppercase letters are accepted. O GLPI grava o método em minúsculas, e o cliente HTTP do 12 só aceita maiúsculas. Isto afeta todos os webhooks, incluindo os criados no 12. O problema está registado no GitHub do GLPI (issue 25883), com correção proposta. Quando testámos, a 16 de outubro, a correção ainda não estava na 12.0.0 nem na versão de desenvolvimento da 12.0.1.

Até a correção sair, o contorno é passar o método para maiúsculas diretamente na base de dados (com cópia de segurança):

UPDATE glpi_webhooks SET http_method = UPPER(http_method);
UPDATE glpi_queuedwebhooks SET http_method = UPPER(http_method);

Se alguém voltar a gravar o webhook pela interface, o campo volta às minúsculas. Nesse caso, repita o comando e acompanhe as notas das versões 12.0.x: quando a correção entrar, o contorno deixa de ser necessário.

4. Depois, o bloqueio da rede interna

Com o método corrigido, o erro mudou: Host "glpiup-hook" is blocked. O GLPI 12 bloqueia por omissão os pedidos do servidor para redes privadas (10.x, 172.16-31.x, 192.168.x). Isto vale para webhooks, calendários externos, feeds RSS e a ligação ao GLPI Network. Por omissão, só os pedidos ao agente de inventário e à autenticação externa ficam permitidos. Se o seu webhook aponta para um n8n, um ERP ou uma API na rede interna, vai parar.

Para permitir só o necessário, crie o ficheiro config/local_define.php na pasta do código do GLPI:

<?php
define('GLPI_SERVERSIDE_URL_ALLOWED_PRIVATE_NETWORKS_CONTEXTS', [
    \Agent::class,    // por omissão
    \Auth::class,     // por omissão
    \Webhook::class,  // permite webhooks para a rede interna
]);

Armadilha do Docker: o GLPI lê este ficheiro em /var/www/glpi/config/, que está dentro da imagem, e não no volume /var/glpi/config. Colocado no volume, o ficheiro não teve efeito. Montado como ficheiro, funcionou:

    volumes:
      - glpi-data:/var/glpi
      - ./local_define.php:/var/www/glpi/config/local_define.php:ro

A partir daí, os dois webhooks da fila foram entregues com status 200. Para configurar um webhook de raiz, veja webhooks nativos do GLPI 11.

5. O aviso sobre documentos

A migração deixou um único aviso no log warning_during_migration_to_12.0.0.log: "Rights have been given for document, you should review ACLs after update". O GLPI atribuiu permissões novas sobre documentos. Reveja em Administração > Perfis, separador Gestão > Documentos, sobretudo nos perfis de utilizador final.

Checklist da atualização

E os módulos do NexTool?

O plugin NexTool e os 37 módulos funcionam no GLPI 11 e no 12 com a mesma versão. Por isso, ao contrário dos plugins acima, é possível atualizá-los antes, ainda no 11, em NexTool > Módulos > Atualizar todos. Depois da migração, ficam suspensos como os outros plugins: execute o plugin:resume_execution e confira a lista em NexTool > Módulos. A tabela módulo a módulo está em NexTool no GLPI 12: compatibilidade. Se quiser apoio para planear ou executar a atualização, fale connosco.

Teste da NexTool a 16 de outubro de 2026, numa cópia descartável com dados fictícios: imagem oficial glpi/glpi 11.0.11 para 12.0.0 (PHP 8.5), MariaDB 10.6 para 10.11, e pacote .tgz em Debian 13 (PHP 8.4). O ambiente foi apagado no final. GLPI é marca registada da Teclib'. A NexTool não é afiliada da Teclib'.