MPM Documentação d70fcd6

Tutorial — do container Mautic ao update de plugins

Este tutorial cobre o fluxo completo, do zero: você tem um Mautic rodando em Docker e sai com plugins instalados, atualizados e gerenciados pelo mpm.

Diferente do Primeiro plugin (5min), aqui cada etapa mostra o que verificar, o que esperar de saída e o que fazer se travar.

Pré-requisitos

  • Docker rodando no servidor
  • Container Mautic ativo (qualquer major: 4, 5, 6, 7)
  • Acesso root/sudo no host
  • Acesso à conta de cliente em https://mng.mtc.codes (pra pegar a API key)

1. Confirmar que o Mautic está no ar 

docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Image}}" | grep mautic

Anote o nome do container (ex: mautic_prod) — vai usar em todas as etapas.

Confirme a versão do Mautic:

docker exec mautic_prod php /var/www/html/bin/console --version
# Mautic 6.3.x - app/prod (env: prod, debug: false)

Se o console falhar com "Could not open input file", provavelmente é um Mautic 4 antigo com app/console em vez de bin/console. O mpm detecta sozinho depois — só anote a major (4, 5, 6 ou 7).

2. Instalar o mpm

O mpm é um binário estático — instalação em um comando:

curl -sL https://mpm.mtc.codes/init.sh | sudo bash

Verifica:

mpm --version
# mpm 0.2.x

Cria três coisas:

  • /opt/mpm/mpm — binário
  • /opt/mpm/config.toml — configuração
  • /usr/local/bin/mpm — symlink

3. Pegar sua API key

Em https://mng.mtc.codes:

  1. Login com sua conta
  2. Menu Conta → API Manager
  3. Clique em Gerar chave
  4. Copie a chave mpm_live_... (ela só aparece uma vez)

Se você já tem key mas perdeu, use Rotacionar — a antiga fica invalidada e você recebe uma nova.

4. Configurar a API key no mpm

Edite /opt/mpm/config.toml:

[api]
base_url = "https://mng.mtc.codes/api/v1"
api_key  = "mpm_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Ou grave por variável de ambiente (não precisa editar o arquivo):

export MPM_API_KEY="mpm_live_..."

Ver detalhes em API key e fingerprint.

5. Registrar a instância Mautic

Um instance é um apelido pra um container. Você pode registrar vários (prod, staging, cliente_x):

mpm instance add prod \
  --container mautic_prod \
  --mautic-version 6 \
  --url https://mautic.seudominio.com.br

mpm instance list

Saída esperada:

Configured Instances
NAME    CONTAINER    MAUTIC  STATUS   URL
prod    mautic_prod  6       running  https://mautic.seudominio.com.br

--mautic-version deve bater com a major do Mautic — se colocar 6 num container M4 o warmup vai falhar (e o mpm faz rollback automaticamente, mas você perde tempo).

Se não souber o nome do container: mpm instance discover lista todos os candidatos.

O catálogo mostra os plugins da sua licença:

mpm catalog refresh
mpm catalog search archive
mpm catalog info archivemaster

refresh cacheia local por 24h — rode de novo se acabou de comprar um plugin novo.

7. Instalar o plugin 

mpm install archivemaster -i prod

Você verá o pipeline de 14 etapas:

[1/14] Resolving source...
[3/14] Downloading/resolving...
[5/14] Extracting ZIP...
[6/14] Validating plugin...
[7/14] Creating backup...
[8/14] Deploying to container...
[9/14] Fixing permissions...
[10/14] Clearing cache...
[11/14] Warming up cache...
[12/14] Running migrations...
[13/14] Enabling plugin...
[14/14] Verifying...

OK Archive Master v6.3.1 installed successfully in 'prod'

Se qualquer etapa falhar, o rollback é automático: o backup do /plugins/ é restaurado e o container fica no estado anterior. Você não vai quebrar o Mautic mesmo se tentar instalar plugin incompatível.

Instalar versão específica 

mpm install archivemaster -i prod --version 6.3.0
mpm install archivemaster -i prod --rc              # último RC

8. Confirmar dentro do Mautic

Duas formas:

mpm list -i prod

Ou via console do próprio Mautic:

mpm console -i prod -- mautic:plugins:reload

No painel do Mautic: Configurações → Plugins — o plugin deve aparecer e estar publicado.

Se instalou mas não aparece, quase sempre é layout docroot.

9. Manter atualizado

Ver o que tem update disponível:

mpm check -i prod
# archivemaster: 6.3.0 → 6.3.1 available
# queryreport:   up-to-date

Aplicar update de um plugin:

mpm update archivemaster -i prod

Aplicar tudo de uma vez:

mpm update all -i prod

Update usa o mesmo pipeline de 14 etapas, mais o backup da versão atual — se der ruim, rollback restaura a versão anterior completa (não fica em estado quebrado).

Automatizar via cron 

# /etc/cron.d/mpm-check
0 3 * * * root /usr/local/bin/mpm check -i prod --json > /var/log/mpm-check.log

Não recomendo update all automático em prod sem revisão — updates podem ter breaking changes. Use check no cron, aplique manualmente.

10. Manter o mpm atualizado 

mpm self-update              # última versão stable
mpm self-update --rc         # release candidate (teste)

O binário é substituído atomicamente. Backup fica em /opt/mpm/mpm.bak (você pode reverter se quiser).

Situações comuns

"426 fingerprint_required"

Seu mpm está desatualizado pra API atual:

mpm self-update

"403 key_revoked" ou "403 key_used_elsewhere"

A API key foi usada em outro servidor. Cada key só pode estar em um "fingerprint" (combinação máquina + container). Rotacione em mng.mtc.codes → Conta → API Manager e use a nova.

Instalação falha no [11/14] Warming up cache

Quase sempre é:

  • Versão do Mautic incompatível — plugin exige M6, container é M4/5
  • PHP muito antigo — o plugin exige 8.1+, container roda 7.4/8.0
  • Extensão PHP faltando (raro) — vejo em mpm status <plugin>

O rollback já preservou seu Mautic. Corrija a base (upgrade Mautic ou PHP) e re-instale.

Update para versão errada 

mpm install archivemaster -i prod --version 6.3.0 --force

--force permite downgrade / reinstall da mesma versão.

Desinstalar 

mpm uninstall archivemaster -i prod

Remove o diretório do plugin e limpa o cache. O backup em /opt/mpm/backups/ fica preservado por `max_backups` uploads (default 3).

Próximos passos

By Borlot.com.br on 10/07/2026

Tags

tutorial container install update ponta-a-ponta