Version Upgrades - Centmin Mod LEMP Stack

1

Centmin Mod Branches

Centmin Mod maintains three active branches, each supporting different OS versions. Upgrading involves two distinct parts: updating Centmin Mod code itself, and upgrading the software it manages (Nginx, PHP-FPM, MariaDB).

Branch	Type	OS Support
132.00stable	Stable	AlmaLinux 8/9, Rocky Linux 8/9, CentOS 7 (EOL)
140.00beta01	Beta	AlmaLinux 8/9, Rocky Linux 8/9, CentOS 7 (EOL)
141.00beta01	Latest Beta	AlmaLinux 8/9/10, Rocky Linux 8/9/10, CentOS 7 (EOL)

Two-Part Upgrade

Upgrading Centmin Mod involves (1) updating the Centmin Mod shell scripts/code via cmupdate, and (2) upgrading managed software (Nginx, PHP, MariaDB) via centmin.sh menu options. See the Installation Guide if you need to do a fresh install instead.

2

Pre-Upgrade Checklist

Before upgrading any component, complete these checks to ensure a smooth process.

Always Back Up First

Create full backups of your configuration files, databases, and website data before any upgrade. Centmin Mod automatically backs up Nginx and PHP configs during upgrades, but you should have your own backups as well.

Verify your current Centmin Mod version by running centmin
Back up database using MariaBackup or mysqldump
Back up Nginx vhost configs at /usr/local/nginx/conf/conf.d/
Back up PHP-FPM pool configs at /usr/local/etc/php-fpm.d/
Save your /etc/centminmod/custom_config.inc persistent settings
Check disk space: ensure adequate free space for compilation (at least 2-3 GB)
Review the Changelog for any breaking changes in the target version

Check current versions of installed components:

nginx -v
php -v
mysql -V
centmin

3

Centmin Mod Update Procedure (cmupdate)

The cmupdate command at /usr/bin/cmupdate is the primary tool for updating Centmin Mod code. This updates the shell scripts that power Centmin Mod's centmin.sh core — it does not upgrade software like Nginx or PHP-FPM.

Update to Current Branch

Run cmupdate to pull the latest code for your current branch via Git:

cmupdate

Switch to Stable Branch

To switch to the 132.00stable branch:

cmupdate
cmupdate update-stable
cmdir
centmin

Switch to Beta Branch

To switch to the 140.00beta01 branch:

cmupdate
cmupdate update-beta
cmdir
centmin

cmdir is a command shortcut equivalent of cd /usr/local/src/centminmod, and centmin is the shortcut for running centmin.sh from the Centmin Mod directory.

Example Output

Example output from cmupdate update-stable:

cmupdate update-stable
No local changes to save
Already up to date.
Switching local code branch to 132.00stable

Cloning into 'centminmod'...
remote: Enumerating objects: 838, done.
remote: Counting objects: 100% (838/838), done.
remote: Compressing objects: 100% (591/591), done.
remote: Total 838 (delta 343), reused 553 (delta 224), pack-reused 0
Receiving objects: 100% (838/838), 23.89 MiB | 30.01 MiB/s, done.
Resolving deltas: 100% (343/343), done.

Completed. Fresh /usr/local/src/centminmod code base in place
To run centmin.sh again, you need to change into directory:
cd /usr/local/src/centminmod

4

Auto Updates via Cron

Centmin Mod supports automatic code updates via cron. Since the initial installation sets up a Git environment, you can schedule /usr/bin/cmupdate as a cronjob to keep your code current.

Set up a cronjob to run every 3 hours using crontab -e:

15 */3 * * * /usr/bin/cmupdate >/dev/null 2>&1

Auto cron updates only update the Centmin Mod shell scripts code. They do not automatically upgrade Nginx, PHP, or MariaDB. Those require running the respective centmin.sh menu options manually.

5

Persistent Settings via custom_config.inc

With auto cron updates enabled, you may wonder if custom settings in centmin.sh will be overwritten. Centmin Mod supports a separate custom_config.inc file for persistent settings that survive code updates.

Two supported locations:

/usr/local/src/centminmod/inc/custom_config.inc
/etc/centminmod/custom_config.inc (recommended)

Example: set a specific PHP version as default:

PHP_VERSION='8.3.15'

Example: enable Nginx IPv6 support and disable unused modules:

NGINX_IPV='y'
NGINX_PAGESPEED=n        # deprecated
NGINX_PASSENGER='n'
NGINX_WEBDAV=n
NGINX_VHOSTSTATS=n

After adding settings to custom_config.inc, recompile the relevant component using the appropriate centmin.sh menu option (Menu 4 for Nginx, Menu 5 for PHP).

6

Nginx Upgrade / Downgrade (Menu Option 4)

Use centmin.sh menu option 4 to upgrade or downgrade Nginx. This compiles Nginx from source with all configured modules. See the full Nginx upgrade documentation for details.

centmin
# Select menu option 4
# Enter the Nginx version number when prompted

Key points about Nginx upgrades:

Nginx is compiled from source with all modules specified in centmin.sh or custom_config.inc
Existing Nginx vhost configs are automatically backed up before the upgrade
You can downgrade to a previous Nginx version using the same menu option
OpenSSL or BoringSSL versions can be customized via custom_config.inc

Nginx Compile Time

Compiling Nginx from source may take several minutes depending on your server's CPU and the number of modules enabled. During compilation, the existing Nginx remains running and serving traffic.

7

PHP Upgrade / Downgrade (Menu Option 5)

Use centmin.sh menu option 5 to upgrade or downgrade PHP-FPM. This compiles PHP from source with all configured extensions. See the full PHP upgrade documentation for details.

centmin
# Select menu option 5
# Enter the PHP version number when prompted

Key points about PHP upgrades:

PHP is compiled from source with all extensions specified in centmin.sh or custom_config.inc
PHP-FPM pool configuration files are preserved during upgrades
Set your preferred PHP version in /etc/centminmod/custom_config.inc using PHP_VERSION='x.x.x'
PECL extensions may need to be reinstalled after a major PHP version change

Major PHP Version Changes

When upgrading between major PHP versions (e.g., PHP 8.1 to 8.3), test your web applications for compatibility. Some PHP functions may be deprecated or removed between major versions.

8

MariaDB MySQL Upgrade & Management (Menu Option 11)

MariaDB MySQL upgrades are handled through centmin.sh menu option 11. Menu option 6 is for MySQL user and database management. See the full MariaDB upgrade documentation for details.

centmin
# Select menu option 11
# Follow the MariaDB upgrade sub-menu prompts

MariaDB minor version updates can also be done via YUM:

yum update MariaDB-client MariaDB-common MariaDB-compat \
  MariaDB-devel MariaDB-server MariaDB-shared

Database Backup Required

Always perform a full database backup using MariaBackup or mysqldump before upgrading MariaDB. Major version upgrades (e.g., 10.x to 11.x) require careful testing and may involve schema changes. Run mysql_upgrade after a major version change.

9

Post-Upgrade Verification

After any upgrade, verify that all services are running correctly.

Check Service Status

systemctl status nginx
systemctl status php-fpm
systemctl status mariadb

Verify Versions

nginx -v
php -v
mysql -V

Test Nginx Configuration

nginx -t
# Expected output: syntax is ok / test is successful

Check Error Logs

tail -50 /var/log/nginx/error.log
tail -50 /var/log/php-fpm/www-error.log
tail -50 /var/log/mariadb/mariadb.log

Also test your websites by loading them in a browser and verifying functionality. Check that PHP applications work correctly and that database connectivity is intact.

10

Rollback Procedures

If an upgrade causes issues, you can roll back to previous versions.

Centmin Mod Code Rollback

Switch back to a previous branch using cmupdate:

# Switch back to stable from beta
cmupdate update-stable

Nginx Rollback

Downgrade Nginx to a previous version using the same Menu Option 4. Enter the previous version number when prompted:

centmin
# Select menu option 4
# Enter the previous Nginx version number

PHP Rollback

Downgrade PHP to a previous version using Menu Option 5:

centmin
# Select menu option 5
# Enter the previous PHP version number

MariaDB Downgrade Not Supported

MariaDB major version downgrades are not supported via YUM. If a MariaDB upgrade causes issues, restore from your pre-upgrade database backup. This is why database backups before MariaDB upgrades are critical.

Need Help?

If you encounter issues during an upgrade, check the Centmin Mod Community Forums for help. The How to Upgrade Centmin Mod thread covers additional upgrade scenarios.