Upgrading a BrowserCMS project
Clone this wiki locally
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.
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
- Back up your database
- Use an SCM (ideally Git)
- Work in development first, with copy of production data
- 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:
- Upgrading to 3.5.x from 3.4.x
- Upgrading to 3.4.x from 3.3.x
- Upgrading to 3.3.3 from 3.3.x
- Upgrading to 3.3.x from 3.1.x (aka Rails 2 to Rails 3)
- Upgrading to 3.1.5 (from 3.1.x)
- Upgrading to 3.1.x (from earlier versions)
4.2 Upgrading Modules
For module built against a specific version of BrowserCMS: