NetLock RMMNetLock RMM Docs
III — How-To Guides

Upgrade MySQL to 8.4 (Docker)

Move a self-hosted NetLock RMM installation from MySQL 8.0 (or 5.7) to the 8.4 LTS release: backup, compose changes, first start and checks.

Upgrade MySQL to 8.4 (Docker)

Self-hosted only: This guide applies to self-hosted deployments. Cloud customers do not run a database server — the hosted platform is run for them.

This guide moves the MySQL container of a self-hosted NetLock RMM installation from MySQL 8.0 (or 5.7) to MySQL 8.4, the current long-term support release. It follows the Docker Compose layout of Install the NetLock RMM server with Docker: the compose file at /home/netlock/docker-compose.yml, the mysql service with the container name mysql-container, and the data directory /home/netlock/mysql/data. Plan for downtime: the server and the Web Console are stopped while the database upgrades its files. On a small installation that is a matter of minutes; on a large database the first start of the new version can take considerably longer (see step 4).

Why and when

Oracle publishes security fixes only for MySQL releases that are still in support:

ReleaseOracle support ended / endsStatus
MySQL 5.731 October 2023Out of support
MySQL 8.030 April 2026 (last release 8.0.46)Out of support
MySQL 8.4 LTS30 April 2032Recommended

The dates follow Oracle's lifetime support policy; a compact overview is kept at endoflife.date/mysql. NetLock RMM is developed and tested against MySQL 8.4, and every current installation path — the guided installer and the compose file in the installation guide — deploys mysql:8.4. Installations created earlier usually still pin mysql:8.0.

The Web Console tells you when the database server is older than 8.4:

  • A warning icon next to the update notice in the top bar (on phones, an entry in the account menu). It opens a short dialog with the running version, the date its support ended, the recommended version, the upgrade steps and a link to this guide.
  • A warning above the status card on Settings → Database, with the same link.

Both are visible to accounts that may open Settings → Database (settings_enabled and settings_database_enabled), only on self-hosted installations, and they stay until the database reports version 8.4 or newer. There is no dismiss button.

Short version

On an installation that follows the Docker layout above, the upgrade takes six steps:

  1. SSH into the NetLock RMM server.
  2. Navigate to /home/netlock
  3. Run sudo docker compose down
  4. Run sudo nano docker-compose.yml
  5. Locate the mysql image entry, change from mysql:8.0 to mysql:8.4, save and exit.
  6. Run sudo docker compose up -d

Keep these points in mind:

  • Take the backup before step 3 of this list: mysqldump needs a running database.
  • down waits only 10 seconds by default. With a large buffer pool use sudo docker compose down -t 120 so MySQL can shut down cleanly.
  • up -d starts everything at once. The Web Console and the server restart until MySQL is ready; do not interrupt the first start.

The sections below are the same upgrade in smaller stages, with the check of the MySQL options that 8.4 no longer accepts. On MySQL 5.7, the note under "Before you start" applies.

Before you start

You need:

  • Shell access to the host that runs the containers, with permission to run docker (the commands below use sudo).

  • The compose file. The installation guide places it at /home/netlock/docker-compose.yml; adjust the paths below if yours differs.

  • The running MySQL version. Settings → Database shows it on the status card. From the host, the container's own client reports it as well; the root password comes from the container's environment, so nothing is typed into the shell:

    sudo docker exec mysql-container sh -c 'mysql -uroot -p"$MYSQL_ROOT_PASSWORD" -e "SELECT VERSION();"'
  • A current backup of the database. Step 1 explains why there is no way back without one.

Note: MySQL 5.7 cannot be upgraded to 8.4 directly — a release series cannot be skipped (upgrade paths). Run this guide twice: first with the image mysql:8.0, wait until that upgrade has finished and the server is up, then again with mysql:8.4.

Note: Pin the image tag. mysql:8.4 stays on the 8.4 series and receives its patch releases through normal image pulls. A container-update watcher such as Watchtower follows the tag you pinned and never moves mysql:8.0 to 8.4 on its own. The tags mysql:8 and mysql:latest already resolve to 8.4 and would jump versions on the next pull without the preparation below, so replace them with mysql:8.4.

Step 1 — Stop the application and check your backup

Stop the two application containers so nothing writes to the database while you work:

sudo docker compose -f /home/netlock/docker-compose.yml stop netlock-rmm-web-console netlock-rmm-server

Make sure you have a current backup of the database before you change the image. There is no way back in place: once 8.4 has started on the data directory, 8.0 will not open it again, and the only route back is a backup loaded into a fresh 8.0 database (downgrading MySQL). If your regular backup has not run since the last changes, take a logical dump now. The root password and the database name are read from the container's environment (MYSQL_ROOT_PASSWORD and MYSQL_DATABASE in the compose file), so neither ends up in the shell history:

sudo docker exec mysql-container sh -c 'mysqldump -uroot -p"$MYSQL_ROOT_PASSWORD" --single-transaction --routines --triggers "$MYSQL_DATABASE"' > /home/netlock/mysql-backup-$(date +%F).sql

Then stop the database container. The stop command waits up to two minutes; the default of ten seconds can end a server with a large buffer pool before it has written everything out.

sudo docker compose -f /home/netlock/docker-compose.yml stop -t 120 mysql

Note: Upgrade only a server that was shut down cleanly; docker compose stop does that. A server that crashed and was not restarted since must be started once and stopped again before you continue (upgrade prerequisites).

Step 2 — Check the MySQL options

MySQL 8.4 refuses to start on options it has removed and writes unknown variable to the log. The compose file from the installation guide passes its options in the command: block of the mysql service; a mounted my.cnf, if you added one, needs the same check. Compare what you have against this table:

OptionWhat to do for 8.4
--skip-log-bin, --innodb_buffer_pool_size, --innodb_flush_log_at_trx_commit, --max_connectionsKeep.
--innodb_log_file_size=256M (older NetLock guides)Replace with --innodb_redo_log_capacity=512M. The old option is deprecated but still accepted; the new one sets the same total (two files of 256M).
--default-authentication-plugin=...Delete. Removed in 8.4; the server does not start with it. See Troubleshooting if accounts were created with mysql_native_password.
--expire-logs-days, --skip-host-cache, --skip-innodb, --innodbDelete. Removed in 8.4.

The list of removed options is in What Is New in MySQL 8.4 since MySQL 8.0; the redo log sizing is described under innodb_redo_log_capacity.

Step 3 — Change the image

In the mysql service of the compose file, change the image tag from mysql:8.0 to mysql:8.4:

  mysql:
    image: mysql:8.4

Leave the rest of the service as it is: the data directory volume, the environment variables and the network settings carry over unchanged.

Step 4 — Start MySQL and watch the log

sudo docker compose -f /home/netlock/docker-compose.yml up -d mysql
sudo docker logs -f mysql-container

Docker pulls mysql:8.4 and starts a new container on the existing data directory, which is how a MySQL container is upgraded (upgrading a MySQL container). On this first start the server upgrades its data dictionary and system tables on its own; no option is needed, this is the default --upgrade=AUTO (what is upgraded). The log shows a line like Server upgrade from '800xx' to '804xx' started, later a matching completed line, and finally ready for connections. Leave the log with Ctrl + C; that does not stop the container.

Note: The upgrade can take a while. On this first start MySQL rewrites its data dictionary and system tables and checks every table of the database. On a small installation that is done in seconds; on a database that has collected events, inventory and patch data for years it can take many minutes, and the time grows with the size of the data directory and the speed of the disk. The container is not stuck while the log stays quiet between started and completed. Do not stop, restart or recreate it during that time: an interrupted upgrade leaves a data directory that only the backup from step 1 brings back.

Step 5 — Start the rest and verify

sudo docker compose -f /home/netlock/docker-compose.yml up -d

Open Settings → Database. The status card shows Version: 8.4.x, the warning above it is gone, and the warning icon in the top bar disappears as soon as the page has read the new version.

Keep the backup from step 1 until the installation has run on 8.4 for a few days.

Troubleshooting

  • The container stops right after the start and the log says unknown variable. An option that 8.4 removed is still in the command: block or in a mounted my.cnf. Go back to step 2, fix the option, and run the up -d mysql command again.

  • The log says Plugin 'mysql_native_password' is not loaded, or an application cannot sign in after the upgrade. The mysql_native_password plugin is disabled by default since 8.4.0. The root account the image creates uses caching_sha2_password and is not affected, and the Web Console's connection parameters keep AllowPublicKeyRetrieval=True, which that method needs. Only accounts created by hand with mysql_native_password are affected. Enable the plugin once by adding --mysql-native-password=ON to the command: block, start the container, and switch the account:

    ALTER USER 'name'@'%' IDENTIFIED WITH caching_sha2_password BY '<password>';

    Then remove the flag again and recreate the container. The plugin change is listed in What Is New in MySQL 8.4 since MySQL 8.0.

  • The log has shown Server upgrade … started for a long time and nothing else. The upgrade is still running; see the note in step 4. Wait for the completed line, do not restart the container.

  • A 5.7 data directory with mysql:8.4. The server refuses to start; a release series cannot be skipped. Set the tag to mysql:8.0, let that upgrade finish, then continue with 8.4.

  • Going back to 8.0. The upgraded data directory cannot be opened by 8.0 again. Stop the database container, move the directory aside, set the tag back to mysql:8.0 and start the container on an empty directory; the image then creates the database and the accounts from the compose environment again. Wait for ready for connections in the log, then load the backup from step 1:

    sudo docker compose -f /home/netlock/docker-compose.yml stop mysql
    sudo mv /home/netlock/mysql/data /home/netlock/mysql/data-8.4
    sudo mkdir /home/netlock/mysql/data
    # change image: to mysql:8.0 in the compose file, then
    sudo docker compose -f /home/netlock/docker-compose.yml up -d mysql
    sudo docker logs -f mysql-container
    sudo docker exec -i mysql-container sh -c 'mysql -uroot -p"$MYSQL_ROOT_PASSWORD" "$MYSQL_DATABASE"' < /home/netlock/mysql-backup-<date>.sql

    Then run the up -d command from step 5. Delete /home/netlock/mysql/data-8.4 once the installation runs again.