Upgrades

Automatic and manual upgrade methods, how to handle modified files, troubleshooting tips and common upgrade issues.

Before You Begin

Before starting any upgrade process, it's essential to take these precautionary steps:

  1. Create a Complete Backup

    • Back up all UNA files and directories
    • Export a full database backup
    • Store backups in a secure location outside your web directory

  2. Review System Requirements

    • Check if your hosting environment meets the requirements for the new version

  3. Check for Customizations

    • Identify any custom code modifications you've made
    • Document custom templates or overridden files
    • Note any third-party modules that aren't from the official UNA store

Understanding UNA Upgrade Channels

UNA offers two upgrade channels to choose from:

Stable Channel

  • Recommended for production sites
  • Contains thoroughly tested releases
  • Less frequent updates but more reliable
  • Default channel for all UNA installations

Beta Channel

  • Recommended for development/testing sites
  • Contains the latest features and improvements
  • More frequent updates but may contain bugs
  • Useful for previewing upcoming features

Switching Between Channels

You can switch between channels in two ways:

  1. Via Studio Interface:

    • Navigate to Studio > Developer > Settings
    • Find the Update channel option
    • Select your preferred channel (stable or beta)

  2. Via Database Query:

    • If the Developer module isn't installed, run this SQL query:
      UPDATE `sys_options` SET `value` = 'beta' WHERE `name` = 'sys_upgrade_channel';

      (Replace 'beta' with 'stable' to switch back)

    • Clear the database cache in Studio > Dashboard > Cache block

Automatic Upgrade Process

The automatic upgrade is the recommended method for most UNA installations.

Enabling Auto-Updates

  1. Navigate to Studio > Settings > System > Site Settings
  2. Enable the Enable auto-update option
  3. Save changes

When auto-updates are enabled, your site will check for and apply updates automatically within 24 hours.

Forcing Auto-Updates with Modified Files

If you have modified UNA core files, the automatic update may be blocked. You can force updates in two ways:

  1. Via Studio Interface:

    • Navigate to Studio > Settings > System > Site Settings
    • Enable Force auto-update, even if some files were modified
    • This will allow updates to proceed if less than 5% of files are modified

  2. Via Code Modification:

    • If more than 5% of files are modified, you can change the threshold by editing:
      // File: inc/classes/BxDolInstallerUtils.php
// Change this line:
define('BX_FORCE_AUTOUPDATE_MAX_CHANGED_FILES_PERCENT', 0.05);
// To:
define('BX_FORCE_AUTOUPDATE_MAX_CHANGED_FILES_PERCENT', 1.00);
    • This allows updates to proceed regardless of the percentage of modified files
    • Warning: This approach may overwrite your customizations

Manual Upgrade Process

If you prefer to control the upgrade process manually, follow these steps:

Step 1: Upgrade the Core System

  1. Log in to your UNA Studio admin panel
  2. Navigate to Studio > Dashboard
  3. Click/tap the Upgrade button
  4. Wait for the system upgrade to complete (usually within a minute)
  5. If it's not upgrading within a minute, check if UNA cron jobs are installed correctly and check logs/upgrade.log for any errors during upgrade.

Step 2: Upgrade All Modules

  1. After the core system is updated, go to Studio > Apps Market > Updates
  2. Review the list of available module updates
    • Note: If you don't have paid licenses, only free module updates will appear
    • Check the Purchases tab to see all your paid modules
  3. Apply all available module updates by clicking the update button for each
  4. After all updates are applied, reload the page
  5. Apply any remaining updates for the same modules until no more updates are available
  6. If some modules aren't upgrading check logs/upgrade_modules.log for any errors.

Step 3: Repeat for Multiple Version Jumps

If you're upgrading across multiple versions (e.g., from 9.0 to 11.0):

  1. Repeat Steps 1-2 for each intermediate version
  2. After each system update from Dashboard, go to Apps Market and apply all module updates
  3. Continue this process until you reach the latest version

Handling Modified Files During Upgrades

When you've customized UNA files, upgrades require special handling to preserve your changes.

Understanding the 5% Rule

UNA's upgrade system will block automatic updates if more than 5% of files have been modified. This is a safety measure to prevent accidental loss of customizations.

Options for Handling Modified Files

  1. Merge Changes Manually (Recommended)

    • If more than 5% of files are modified, manually merge your changes
    • Use a file comparison tool to identify differences
    • Apply your customizations to the new version files
    • This approach preserves your changes but requires technical knowledge

  2. Force Updates (Caution)

    • Enable the "Force auto-update" option in settings
    • Or modify the BX_FORCE_AUTOUPDATE_MAX_CHANGED_FILES_PERCENT constant
    • Warning: This may overwrite your customizations

  3. Create Custom Modules Instead

    • Rather than modifying core files, create custom modules
    • Use alerts(hooks) to modify functionality
    • This approach makes future upgrades much easier

Best Practices for Customizations

To minimize upgrade issues with customized installations:

  1. Document All Changes

    • Keep a detailed log of all files you modify
    • Document the purpose of each change

  2. Use Version Control

    • Maintain your UNA installation in a Git repository
    • Create branches for customizations
    • This makes it easier to track changes and merge updates

  3. Prefer Template Overrides

    • Instead of modifying core template files, create overrides
    • Place custom templates in the proper override directories

  4. Use Hooks Instead of Core Modifications

    • Utilize UNA's alerts/hook system to extend functionality
    • This avoids direct modification of core files

Troubleshooting Common Upgrade Issues

Update Button Keeps Loading

Issue: After clicking the update button, it keeps loading indefinitely.

Solutions:

  1. Check your PHP error logs for specific errors
  2. Ensure your cron jobs are properly configured and running
  3. Verify you have sufficient server resources (memory, CPU)
  4. Try clearing the browser cache and cookies
  5. Check server PHP timeout settings

Database Errors During Upgrade

Issue: SQL errors or database connection issues during upgrade.

Solutions:

  1. Check database user permissions
  2. Verify database server is running properly
  3. Ensure your database meets the minimum version requirements
  4. Check for database corruption and repair if necessary

Broken Functionality After Upgrade

Issue: Some features stop working after the upgrade.

Solutions:

  1. Update all modules, not just the core system
  2. Clear all caches (UNA cache, browser cache)
  3. Check for JavaScript errors in the browser console
  4. Verify compatibility between modules and the core version

Post-Upgrade Tasks

After successfully upgrading your UNA installation:

  1. Test All Functionality

    • Verify all critical features work correctly
    • Test on different devices and browsers
    • Check both front-end and admin functionality

  2. Update Custom Code

    • Review and update any custom code for compatibility
    • Apply necessary changes to custom templates
    • Update custom modules if needed

  3. Optimize Performance

    • Run database optimization if needed
    • Clear all caches
    • Check server load and performance

  4. Update Documentation

    • Update your internal documentation with new features
    • Note any changes in configuration or behavior

Special Considerations for Major Version Upgrades

When upgrading between major versions (e.g., UNA 9 to UNA 10, or UNA 10 to UNA 11):

Database Schema Changes

Major versions often include database schema changes. These are handled automatically during the upgrade process, but may take longer to complete.

Template Changes

Major versions may include significant template changes. If you've customized templates:

  1. Review the new default templates
  2. Update your custom templates to match the new structure
  3. Test thoroughly after upgrading

API Changes

Major versions may include API changes that affect custom modules:

  1. Review the changelog for API modifications
  2. Update custom modules to use the new API
  3. Test all custom functionality after upgrading

Upgrading in Different Environments

Shared Hosting

  • Schedule upgrades during low-traffic periods
  • Increase PHP memory limit if possible
  • Be prepared for longer upgrade times

VPS/Dedicated Server

  • Consider setting up a staging environment for testing
  • Adjust server settings for optimal performance during upgrade
  • Monitor server resources during the upgrade process

Development/Staging Environment

  • Always test upgrades in a staging environment first
  • Document the upgrade process and any issues encountered
  • Use the beta channel for earlier access to updates

Conclusion

Regular updates are essential for keeping your UNA CMS installation secure, stable, and equipped with the latest features. By following this guide and best practices, you can ensure smooth upgrades with minimal disruption to your community.

Remember to always back up your site before upgrading, test thoroughly after upgrading, and maintain good documentation of any customizations you've made to simplify future upgrades.

On This Page