Upgrading Mautic 5.2.3 → 6.0.7 (Docker, MariaDB 11.8)

Environment

• Docker: PHP 8.3-fpm + nginx + supervisord
• MariaDB 11.8 (shared Coolify-managed container)
• Volumes: config, media, plugins, themes, var, translations

Gotcha 1: Plugin Volume Override

After swapping the html/ source to 6.0.7, the Docker volume mount for plugins/ still contains 5.2.3 plugins. These reference the session Symfony service which was removed in Symfony 6.

Symptom:

The service "mautic.integration.gmail" has a dependency on a non-existent service "session"

Fix: Sync plugins from the fresh image to the volume:

docker compose stop mautic
PLUGIN_VOL=$(docker volume inspect mautic_mautic-plugins --format '{{.Mountpoint}}')
rm -rf ${PLUGIN_VOL}/*
docker run --rm -v mautic_mautic-plugins:/dest --entrypoint bash mautic-mautic \
  -c "cp -r /var/www/html/plugins/* /dest/"
# Same for themes volume

Gotcha 2: MariaDB 11.8 Blocks Charset Conversion on FK Columns

Migration Version20211020114811 converts tables from utf8mb3 to utf8mb4. It sets SET FOREIGN_KEY_CHECKS=0 but MariaDB 11 still returns error 1832/1833 when ALTER TABLE touches columns with FK constraints.

Fix: Drop all FKs, convert tables, re-add FKs:

# Generate drop/add scripts
docker exec mariadb mariadb -uroot -p$PASS $DB -N -e "
  SELECT CONCAT('ALTER TABLE \`', TABLE_NAME, '\` DROP FOREIGN KEY \`', CONSTRAINT_NAME, '\`;')
  FROM information_schema.TABLE_CONSTRAINTS
  WHERE TABLE_SCHEMA = '$DB' AND CONSTRAINT_TYPE = 'FOREIGN KEY'" > /tmp/drop_fks.sql

# Save FK re-add statements BEFORE dropping (include ON DELETE/UPDATE rules)
# ... (generate from KEY_COLUMN_USAGE + REFERENTIAL_CONSTRAINTS)

# Execute: drop → convert → re-add
docker exec mariadb mariadb -uroot -p$PASS $DB -e "source /tmp/drop_fks.sql"
docker exec mariadb mariadb -uroot -p$PASS $DB -e "source /tmp/convert_charset.sql"
docker exec mariadb mariadb -uroot -p$PASS $DB -e "source /tmp/add_fks.sql"

Gotcha 3: Index Key Too Long for utf8mb4

plugin_citrix_events has composite indexes on multiple VARCHAR columns. In utf8mb4 (4 bytes/char), 255*4*4 = 4080 bytes > 3072 max.

Fix: Drop index, convert table, recreate with prefix lengths:

DROP INDEX citrix_event_product_name ON plugin_citrix_events;
ALTER TABLE plugin_citrix_events CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE INDEX citrix_event_product_name ON plugin_citrix_events(product(191), email(191), event_type, event_name(191));

Gotcha 4: Traefik Container Discovery

After docker compose down && up -d, Traefik (v3.6) didn't discover the new container's labels.

Fix: docker restart coolify-proxy (Traefik container)