Upgrading

If you're using Cerb Cloud then we handle upgrades for you already.

The officially supported way of upgrading Cerb is by using Git1, a distributed version control system. The latest stable build of the project can be found on GitHub. This environment makes it much easier for people to collaborate and share improvements.

You can use Git to quickly update your local Cerb files to the latest version. The major advantage of version control is that it will attempt to automatically merge official code improvements with any local configuration and customization you have performed. Git also gives you the ability to list all your changes to any project files, and to easily restore to an official version when desirable.

On Unix-based servers you can check if Git is installed by typing:


git --version

If you need to install Git, it’s usually available in a package named git. The actual package name will depend on your operating system.

If you can’t use Git, you really should consider using Cerb Cloud rather than managing it yourself.

Preparation

  • Always make a backup of your Cerb database prior to upgrading. See the chapter on Backups for more information.

  • Change directory to your cerb installation.


cd /path/to/cerb/

Update using Git on a Unix-based server

Verify that you’re using Git:


git status

You can also verify that a .git directory exists. If the above command returns an error, or the .git directory doesn’t exist, then you probably installed the software a different way. You should reinstall Cerb from GitHub2.

Restore the /install directory:


git checkout -- install

Verify that you’re using the proper remote repository:


git remote -v
origin	https://github.com/cerb/cerb-release.git (fetch)
origin	https://github.com/cerb/cerb-release.git (push)

If your origin isn’t https://github.com/cerb/cerb-release.git, then run the following commands:


git remote rm origin
git remote add origin https://github.com/cerb/cerb-release.git
git fetch origin

Stash your uncommitted local changes (like your framework.config.php configuration file). This leaves you with a clean version of the project files that simplifies merging:


git stash

Switch to the master branch if it’s not your current branch:


git checkout master

Update to the latest stable version:


git pull origin master

Reapply your local file changes:


git stash pop

Remove the ./install directory:


rm -Rf install

Dealing with conflicts

If you encounter conflicts while updating, you can attempt to resolve them manually, or you can revert your changes and restore your framework.config.php settings by hand. Don’t simply copy over the new file with your old file, because it may have changed in the recent version.

Ensure that you have no remaining conflicts before continuing with the upgrade.


git status

A handy tool to visualize and reconcile conflicts is built into Git:


git mergetool

Finishing the Upgrade

Permissions

You should set file ownership and permissions again after updating your files.

Unix-based servers

Change directory to your Cerb installation:


cd /path/to/cerb/

Set owner:group to the webserver (this may be different in your environment):


chown -R www-data:www-data .

Set read file permissions for owner and deny everything else:


find . -type f -exec chmod 400 {} \;

Set read/list directory permissions for owner and deny everything else:


find . -type d -exec chmod 500 {} \;

Recursively grant write permission to owner on the storage directory:


chmod -R u+w storage/

Replace www-data with your webserver's user and group.

Windows-based servers

Use Windows Explorer to set the appropriate write permissions on the /cerb/storage directory for your IIS user.

Database schema updates

Some Cerb updates contain database changes which require an administrator to finalize. This will prohibit all Cerb activity (e.g., logins, scheduled tasks, mail parsing) to prevent any database corruption while you’re between versions.

After your files are updated, attempt to log into your Cerb instance as you normally would. If a database update is required the software will automatically prompt you. Upon finalizing you should be able to log in and continue working.

Community Portals

Very rarely, the index.php file which drives Community Portals like the Support Center may change during an upgrade.

How to tell if you need to update your Community Portal file:

  • Log into Cerb.
  • Click setup from the top right.
  • Click the Configure menu and select Community Portals.
  • Select any portal to edit it.
  • Click the Installation tab.
  • Compare the following line from the output with your deployed index.php:

define('SCRIPT_LAST_MODIFY', 1234567890); // last change

  • If the number is different you should replace the index.php file for your community portal with the new version from Cerb.

This is only required if you used the bundled index.php file to deploy a portal. This step isn't necessary if you use a true reverse proxy (e.g. Nginx or Apache mod_proxy) to serve your community portals.

References