Upgrading a BrowserCMS project

peakpg edited this page Jul 12, 2012 · 33 revisions
Clone this wiki locally

1. Overview

One of the goals for the BrowserCMS project is to make upgrades as easy as possible. We provide some built in tools to help make this easier (like bcms upgrade) but due to the custom nature of each project, there will likely be some manual steps that will require review. In particular, upgrading BrowserCMS will also tend to require updating to a newer version of Rails, which has its own set of challenges.

2. Prerequisites

Before getting started, take note of what version of BrowserCMS and Rails you are currently running. Then consult section 4 below and find the most relevant instructions for your upgrade. The 'safest' option is probably to upgrade completely one step at a time (i.e. 3.3.x -> 3.4.x, then 3.4.x -> 3.5.x), but that will certainly take more time than just skipping a version.

3. Warnings: Before Starting

  1. Back up your database
  2. Use an SCM (ideally Git)
  3. Work in development first, with copy of production data
  4. Have backups of file uploads

3.1 Backup your data

This should probably go without saying, but upgrades can be risky. New versions of BrowserCMS may involve adding migrations, changing existing data and altering files.

3.2 Use SCM

Using a Source Control system is essential (and hopefully you are already doing it). Git will work best, as many of the upgrade scripts will automatically revert files using Git. It's a good idea to start with a clean working directory, so you can revert changes made.

3.3 Test in development first

It's ideal to test these migrations on a copy of the database, with a matching copy of the uploads directory first. This will allow you to compare files to make sure they exist and are displaying correctly after the migrations run.

3.4 Backups of Uploads

Some versions of BrowserCMS may make changes/work with the uploads directory, which is where BrowserCMS stores uploaded files. It's a good idea to have a copy of the production files as a backup for testing.

For OSX/Linux users, you can do this (assuming the deafult, that files are stored in tmp/uploads) via:

$ mkdir tmp/uploads-backup
$ cp tmp/uploads/* tmp/uploads-backup

4. Version specific instructions

Based on what version of BrowserCMS you want to upgrade to (and from), see the following list:

4.1 Upgrading Projects

For projects (i.e. sites) using BrowserCMS:

4.2 Upgrading Modules

For module built against a specific version of BrowserCMS: