|Use this document to UPGRADE CiviCRM installations on Drupal to the latest 3.0 release from version 2.2 or earlier 3.0 version.|
|Version 3.0 Requirements|
Before beginning this upgrade, verify that your server meets the requirements for CiviCRM 3.0.
- CiviCRM 2.2.x+ : You must be running CiviCRM 2.2.x to use this upgrade. Running a version prior to 2.2? First upgrade to 2.2 using these instructions
- Drupal 6.x : CiviCRM 3.0 is been built to run under Drupal 6 and is not compatible with Drupal 5 sites.
- PHP 5.2.x : Starting with the 1.9 release, CiviCRM will NOT run on PHP4 servers. CiviCRM 3.0 is also NOT compatible with PHP 5.3. (more info...).
- MySQL 5.0.x or higher : CiviCRM is compatible the current generally available MySQL release.
|Upgrade a Copy of Your Site First and Make a Complete Backup|
We strongly recommend that you create a copy of your existing site (directories and database) - and upgrade that copy first in order to make sure you can complete the upgrade successfully. In any case, you should create a full backup of the installed civicrm directory tree and civicrm database before beginning the upgrade process.
If you are upgrading a COPY of your production 2.2 site - make sure the site you are about to upgrade is a fully functioning 2.2 installation before you begin the upgrade process. (more info...)
Step-by-step Upgrade Procedures
1. Download the most recent 3.0 CiviCRM Package
2. Take the Site Offline (for production site upgrades)
When upgrading a production site, it is recommended that you take your site offline during the upgrade process.
Administer » Site Configuration » Site Maintenance
3. Disable all CiviCRM integration / extension modules (NOT CiviCRM itself)
If you have modules installed in your Drupal site that integrate with or extend CiviCRM functionality, you should disable them prior to running the upgrade script. This will prevent modules that are not compatible with the new version from triggering errors in the upgrade process.
Administer » Site Building » Modules
Note which modules in the CiviCRM section of the modules listing are currently enabled (taking a printing a screenshot is one easy way to do this). Now un-check the Enabled box for ALL modules in the CiviCRM section of the modules listing EXCEPT for CiviCRM itself. Click Save.
Do NOT disable CiviCRM itself. Only disable other modules in the CiviCRM section of the modules page. The upgrade will NOT run if CiviCRM is disabled.
4. Backup your CiviCRM database
Refer to the MySQL reference manual or the phpMyAdmin documentation if you need information on backing up your database.
5. Backup and then delete all 2.2 (or earlier 3.0 versions) code files
CiviCRM will not run properly if files from previous version like 2.2 (or an earlier 3.0 release) are present after the upgrade. Make sure you have a good backup of your complete 2.2 installation and then delete /sites/all/modules/civicrm.
Be sure that your backup copy of the previous version codebase is NOT located below the <drupal home>/modules or <drupal home>/sites/all/modules directory. For example, placing your codebase backup in <drupal home>/modules/civicrm.bak... will cause errors (Drupal executes any *.module files that are found in the modules or sites/all/modules directory tree).
6. Unpack the latest 3.0 package and verify permissions
- Unpack the 3.0 files into <drupal home>/sites/all/modules/.
- You should now have a new civicrm directory tree under the <drupal home>/sites/all/modules/ directory.
- Ensure that your Drupal files directory is writeable by the webserver. You can use the following command to set proper permissions:
7. Run the Upgrade script
This step is required for ALL upgrades.
|MySQL 4.0 and 4.1 are Not Supported|
Support for MySQL versions 4.0 and 4.1 has been discontinued. This means that you may encounter various issues and/or unexpected behavior if you attempt to run CiviCRM under these versions, and the CiviCRM engineering team will not provide support for debugging or resolving these issues. You are strongly encouraged to upgrade to the current generally available release of MySQL.
* Point your web browser to the following URL (you should already be logged in to Drupal with administrator-level permissions):
- *- If "clean URLs" are enabled
*- If "clean URLs" are NOT enabled
- You should see the Upgrade screen.
- If you are ready to upgrade, click the Upgrade Now button.
- You should see the message Upgrade successful when the upgrade completes.
- If you receive any errors during the process, please note down the exact error message, and check for solutions on the community support forum.
- Now click the Return to CiviCRM home page link. This will rebuild CiviCRM menus automatically and return you to the CiviCRM home dashboard. You should the message Menu has been rebuilt.
8. Verify and Update Resource URL Settings
- Go to Administer CiviCRM » Global Settings » Resource URLs
- Refer to the field help on that screen for instructions.
9. Enable Components
If you plan on using the new CiviCase component, or any components that you weren't using in the prior version (e.g. CiviPledge or CiviGrant for grant management) - you'll need to enable these component(s):
- Go to Administer CiviCRM » Global Settings » Enable Components
If you have been using Cases in 2.2 and / or want to start using the CiviCase component, you will also need to complete additional configuration steps. Learn more...
10. Review and Update Drupal Permissions Settings
- It's a good idea to verify Drupal role-based permissions which were added in recent releases. You can review and update these at Administer » User Management » Permissions:
- access CiviMail subscribe/unsubscribe pages : Enable this permission for the anonymous user role if you want any contact in your database to be able to subscribe to public "Mailing List" groups from http://<drupal_site>/civicrm/mailing/subscribe?reset=1 AND to unsubscribe by clicking a web-link in your mailings.
- view event participants : If you want to allow some constituents to see a list of registered participants for a given event at http://<drupal_site>/civicrm/event/participant?id=N&reset=1, then enable this permission for the appropriate Drupal role(s).
- access all custom data : You must enable this permission for any role which you want to view or edit custom data fields. EXAMPLE: If your site uses Profile(s) which include custom fields - make sure the role(s) that need to access these Profiles have this permission.
- access Contact Dashboard : You can now provide authenticated users with access to a screen where they can review their subscribed groups, contributions, memberships and event registrations (as applicable). Enable this permission for role(s) for which you want to provide this feature.
- access CiviEvent : If you plan to use CiviEvent, enable this permission for role(s) which will be creating and managing Events and Event Participants.
- register for events : If you plan to use CiviEvent and want to allow online event registration - enable this permission. Be sure to assign this permission for the "anonymous" role if you want to allow un-authenticated visitors to register for events.
11. Re-enable compatible CiviCRM integration / extension modules
Administer » Site Building » Modules
Go through your list of CiviCRM integration / extension modules and confirm compatibility with the new release if applicable. (If you've downloaded the module from Drupal.org - check the module's page for compatibility information.)
Re-enable all compatible modules by re-checking the Enabled box. You may want to do this "one at a time" if you're unsure of compatibility.
12. Clear Views' cache (for sites using Views 2 integration)
- If you were using Views integration prior to this upgrade, you will need to go to Administer › Site building › Views › Tools and press "Clear Views cache" for Views to capture changes in the CiviCRM Views integration code.
13. Put the Site Online (for production site upgrades)
- Toggle the following feature, and put your site back online:
Administer » Site Configuration » Site Maintenance
- Review Your upgraded site and verify that your data is intact.
- Check out the new features and improvements. A summary of the cool new stuff can be found here.
Check this section for answers to upgrade problems. If your problem isn't addressed here, check out the Installation and Configuration Trouble-shooting page for additional resources.
Page Not Found error
if you get this error when trying to upgrade the database in step 7, you most likely disabled CiviCRM in step 3. Here's how to fix it and get back on track. In short, you have to restore the original version of civicrm, re-enable the module, and then replace the old files with the new.
- Rename the sites/all/modules/civicrm folder to civicrm_new.
- Copy the civicrm folder from your backup into sites/all/modules/
- Go to Administer » Site Building » Modules, check the box next to CiviCRM, and click save.
- Now rename sites/all/modules/civicrm to civicrm_old.
- Rename sites/all/modules/civicrm_new to civicrm.
- Go to Step 7 and try it again. Everything should be back to normal!!
- If so, then don't forget to delete sites/all/modules/civicrm_old.
Reset Your User Session
If you are getting foreign key constraint errors when trying to add or modify records, you may need to reset your user session.
- Temporarily enable CiviCRM debug features:
- Go to Administer CiviCRM » Global Settings » Debugging
- Set Enable Debugging to Yes and click Save.
- Click the Administer CiviCRM menu (or any other CiviCRM menu item). After the page is loaded, add an additional query string value (sessionReset=2) to the URL in your browser's location bar, and reload the page.
- Now reset Enable Debugging to No and click Save.
|Do Not Leave Debug Features Enabled for a Public Site|
Debugging should be disabled for publicly available sites as it may allow browsers to view system configuration information.
Verify and Update Base Directory and Base URL Settings in the Database
If you are seeing problems with missing images or page styling, you may need to adjust the Base Directory and Base URL Settings in the database. You can do this from:
Administer CiviCRM » Configure raquo; Update Directory Path and URL
Verify and Update Configuration Settings File
CiviCRM in versions 2.2 stores most configuration settings in the database. However values needed to load the code and database are stored in the settings file and may need to be updated prior to beginning the upgrade process if you are upgrading a copy of your working 2.2 site:
<drupal home>/sites/xxx/civicrm.settings.php (usually /sites/default/civicrm.settings.php).
- Open civicrm.settings.php with your favorite editor and verify or update the following values:
- $civicrm_root : If you are running this installation in a different directory from your 2.2 site, update this setting with the new path.
- CIVICRM_TEMPLATE_COMPILEDIR : If you are running this installation in a different directory from your 2.2 site, update this setting with the new path.
- CIVICRM_UF_BASEURL : If the Drupal URL for this site is different from your 2.2 site, update this setting with the base URL for your Drupal home page.
- CIVICRM_UF_DSN : If this install will be using a different database for Drupal, update this setting.
- CIVICRM_DSN : This setting must contain the correct information for your 2.2 database. If you are upgrading a copy of your 2.2 database that has a different database name - you will need to change the civicrm_db portion of the setting below. Also review the other values to make sure they are correct for the database that will be used for 3.0.
- CIVICRM_SITE_KEY : If you are upgrading to 3.0 from a version earlier than 2.0.7, you will need to define your CIVICRM_SITE_KEY. Components such as CiviMail's cronjob will not function without the site key with CiviCRM 3.0. Learn how to define the site key here: http://wiki.civicrm.org/confluence/display/CRMDOC/Command-line+Script+Configuration
A fatal error appears when I try to load a CiviCRM page.
This error likely indicates that the new CiviCRM configuration file is not in the expected location or that the $civicrm_root setting is incorrect. See step 3 above.
Foreign Key Errors or Warnings During the Database Upgrade
Foreign keys may have been assigned different names on some installations. Also, different versions of MySQL handle the dropping and adding of constraint checks differently. Try this procedure or this procedure (on the forum) to reload your data into a new 3.0 database structure if you are having this type of issue with upgrading your database.
Download and run Database Troubleshooting Tools to test the current state of the database and provides a diagnosis. The tools suite also includes a repair facility.
If your CiviCRM codebase is NOT located in either <drupal root>/modules/civicrm or <drupal root>/sites/all/modules (i.e. you are using a symlink from there to your codebase) - you will need to create a local file in the top-level directory of your codebase which points to the location of your drupal sites directory.
Access Forbidden (403) Error After Upgrade
This may be caused by directory permission settings. Make sure your <drupal home>/files/civicrm directory is set with chmod a+rwx -R
If you're still getting this error and have clean URLs enabled, try disabling clean URLS (Drupal >> admin >> settings) prior to running the session reset and cleanup. Then re-enable clean URLs.
Screen grays out and a camera icon appears whenever you click any link in CiviCRM
This error is caused by a known problem in the Drupal Lightbox2 module. Either disable the module in Administer » Site Building » Modules or upgrade to the dev version of the Lightbox2 (dated July 2009 or later) that fixes this issue.
Having strange problems with Administrative settings forms after upgrade? Try this: http://wiki.civicrm.org/confluence/pages/viewpage.action?pageId=2981949 or try deleting all files in [yoursite]/sites/default/files/civicrm/templates_c/
UpdateMembershipRecord.php won't run after upgrading from prior versions
Double check that there is a Membership Status Rule called "Deceased" and that it is active in Administer » CiviMember » Membership Status Rules. The solution is described in this forum thread.