Upgrading

Generally, upgrading involves uploading the updated files over your previous version.

Note

These instructions use /cmsb/ as the directory name. Substitute your actual installation directory as needed.

Upgrade Steps

1. Obtain the latest CMS version and verify your server meets the system requirements listed in the installation instructions.

2. Create a backup under Admin Menu > Backup & Restore. The recommended option is Website Backup, a one-click zip of your entire web root, data folder, and a database dump.

   • Lighter alternative: a Database Backup saves just a snapshot of your MySQL data to the data folder’s backups/ directory (the exact path is shown on the Backup & Restore page)
   • Tip: For older CMS installations or large databases, use phpMyAdmin or similar tools for backup.

3. Download the /cmsb/ folder contents and any uploads (if you’ve modified the uploads folder path) to a backup folder on your computer, or just download the Website Backup zip from step 2. Do not modify the backup files.

4. Unzip the CMS program archive and upload the /cmsb/ folder with all contained files.

   • Note: Only original program files are overwritten; data files created by the CMS have unique filenames and won’t be replaced.
   • Update your plugins at the same time. Plugins declare a minimum CMS version (“CMS Version Required” in the plugin header) and won’t activate below it.

5. Run the program.

   • On your next visit to the CMS Admin, the CMS detects the new version and runs the upgrade: schema changes are applied, any missing tables and fields are created, and the version change is recorded in the audit log. The migration is locked while it runs. Concurrent visitors see an “Upgrade in progress” page that refreshes until it completes.
   • Note: The program automatically checks file and directory permissions and alerts you to any required changes. When upgrading from older versions, your browser may refresh multiple times during the upgrade process.

Complete!

Upgrading from version 2.xx to 3.xx

Several code changes since v2.xx require updates. Errors are typically logged in the “Developer Log” menu within the Admin section.

• Some plugins need updating for CMS Builder 3.xx compatibility. Download the latest plugins at: https://www.interactivetools.com/add-ons/
• For custom code errors, consult the instructions and tips below plus the how to upgrade.txt file in the CMS Builder zip.
• For additional questions, post in the forum.

Advanced Tips

Troubleshooting “Internal Server Error” issues

The CMS includes default server config files in /cmsb/ named .htaccess, .user.ini, and php.ini. These attempt to reset PHP and Apache settings to standard values while disabling deprecated or problematic features.

These files aren’t supported on all servers, but on many they will prevent problems. They are optional and can be safely removed.

If errors occur during the upgrade, try these steps sequentially until the errors stop:

1. Disable /cmsb/php.ini by renaming it to php.ini.disabled
2. Disable /cmsb/.htaccess by renaming it to .htaccess.disabled
3. Disable /cmsb/.user.ini by renaming it to .user.ini.disabled
4. Contact support or post in the forum.

Manual MySQL backups and restores

For older CMS installations or extra large databases, use phpMyAdmin, mysqldump, or similar programs for backup and restore. Contact your web host or server administrator for details.

Upgrading sites with custom changes

Modifying CMS program files is not recommended since upgrades will overwrite your changes. Most program behavior modifications can be accomplished through plugins. If custom program file changes are necessary, create a file under /cmsb/ called _CUSTOM_CHANGES_.txt documenting your modifications. This helps remind developers of custom changes and simplifies recreating them after future upgrades.