Guide for Administrators

Upgrades

The officially supported way of upgrading Cerb is by using Git [1], a distributed version control system. The official project is hosted 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-core. The actual package name will depend on your operating system.

If you can’t use Git, you really should consider having us host your copy of Cerb on our On-Demand network 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.

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 GitHub [2].

Restore the /install directory:

$ git checkout -- install

Update the list of branches from the remote repository:

$ git fetch origin

Note

If this gives an error, you can check your list of remotes with the git remote command. Use another remote in place of remote.

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 (and it’s the same reason we restore the install directory before updating):

$ git stash

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

$ git checkout stable

Update to the latest stable version:

$ git pull origin stable

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:

From your cerb/ directory at the console:

chown -R www-data:www-data .

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

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

chmod -R u+w storage/

Note

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 Tools

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

How to tell if you need to update your Community Tool 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 index.php output with your deployed index.php:

    define('SCRIPT_LAST_MODIFY', 2012101301); // last change
  • If the number is different you should replace the index.php file for your community portal with the new version from Cerb.

Note

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. Apache mod_proxy or Nginx) to serve your community portals.

Install directory

Delete the install/ directory if it exists:

$ rm -Rf install/

Footnotes

[1]Wikipedia: Git http://en.wikipedia.org/wiki/Git_(software)
[2]Convert an existing Cerb installation to Git http://cerbweb.com/support/kb/article/71-Switching_a_Cerb5_installation_from_Subversion_to_Git
Next topic:
Backups »