Permalink
Browse files

Extensively clean and re-organize upgrade docs

* Try to avoid duplicating content. Instead link to content when it's
the same across many pages.
* Move all troubleshooting docs into a dedicated troubleshooting page.
* Remove some troubleshooting items that seem dated.
* Link to some "pre upgrade" and "post upgrade" steps that are the same
for all CMSs.
* Write some new content on upgrades, generally.
* Clean up markdown
* Improve headings to be simpler and better nested, where possible
  • Loading branch information...
seanmadsen committed Sep 24, 2017
1 parent 68c5766 commit fb662ea6ed12d635bc3fc7b3ddf927fe021af59a
Showing with 460 additions and 758 deletions.
  1. +1 −1 docs/requirements.md
  2. +178 −92 docs/troubleshooting.md
  3. +71 −387 docs/upgrade/drupal7.md
  4. +71 −0 docs/upgrade/index.md
  5. +30 −118 docs/upgrade/joomla.md
  6. +0 −27 docs/upgrade/misc.md
  7. +42 −0 docs/upgrade/version-specific.md
  8. +65 −131 docs/upgrade/wordpress.md
  9. +2 −2 mkdocs.yml
View
@@ -37,7 +37,7 @@ See our page on [choosing a CMS](/planning/cms.md) for more information about th
### Joomla
* Joomla 2.5.x or 3.x.x is required.
* Joomla 3.x.x is required.
### Backdrop
View

Large diffs are not rendered by default.

Oops, something went wrong.
View

Large diffs are not rendered by default.

Oops, something went wrong.
View
@@ -0,0 +1,71 @@
# Upgrades
Keeping CiviCRM up-to-date helps you take advantage of new features but is critically important when [security updates](https://civicrm.org/security) are issued.
In general:
* The upgrade steps are different depending on your CMS.
* The upgrade steps are the same no matter which versions of CiviCRM you are moving _from_ and _to_ ([with some exceptions](/upgrade/version-specific.md))
* The upgrade steps are the same for small upgrades (e.g. 4.7.10 to 4.7.11) as they are for large upgrades (4.6.7 to 4.7.12).
* You can make big jumps in one upgrade (e.g. 4.5.2 to 4.7.20) without needing to apply all the upgrades in between.
This page provides some of the steps to do before and after an upgrade, but leaves the bulk of the steps up to the CMS specific pages in this chapter.
## Before upgrading {:#before-upgrading}
Before upgrading CiviCRM, follow these steps to ensure the process goes a smoothly as possible.
1. Ensure that your system meets all the [requirements](/requirements.md) for the CiviCRM version to which you are upgrading.
1. Check for any [version-specific upgrade instructions](/upgrade/version-specific.md).
1. **[Backup your site](/setup/backups.md). Very important!**
1. Use your backup to create a _copy_ of your site (directories and database), and ensure that this copied site works correctly. This step is important both for (a) testing that your backup/restore procedure works, and (b) allowing you to test the upgrade in a low-stakes environment.
1. Test the upgrade process on your _copied site_ to ensure that it succeeds.
1. [Troubleshoot](/troubleshooting.md) any upgrade problems.
1. Once you have performed a successful *test* upgrade, *then* apply the same steps on your live site.
## Upgrading
These steps vary depending on your CMS. Find the appropriate page in this chapter and follow the steps within it.
## After upgrading {:#after-upgrading}
### Update resource settings
If you are running the upgrade in a different directory from your previous version you may need to update the configured **CiviCRM Resource URL** and **Extension Resource URL** settings. (Missing icons and images, as well as problems with javascript functions and stylesheets are all symptoms indicating that these settings need to be updated.)
1. Go to **Administer CiviCRM » System Settings » Resource URLs**
1. Refer to the field help on that screen for instructions.
### Updating message templates
If your organization has modified the default versions of System Workflow message templates, then the changes and bug fixes included in an upgrade will need to be merged with your modified versions.
There are a few methods mentioned in this blog [https://civicrm.org/blogs/andrewhunt/upgrade-custom-templates](https://civicrm.org/blogs/andrewhunt/upgrade-custom-templates)
The focus here is on the one that seems most low tech - [http://sourceforge.net/projects/kdiff3](http://sourceforge.net/projects/kdiff3)
You can identify altered templates on the System Workflow Messages screen. The altered ones show 'Revert to default' & 'View Default'. You need to view the new Default versions, & compare them with what you see in the 'Edit' linked page (which will be the latest version used by your organization).
![](https://wiki.civicrm.org/confluence/download/attachments/135135258/TemplatesToUpdate.jpg?version=1&modificationDate=1399945725000&api=v2)
So, for #1 e.g.
We go into the'View Default' link & copy the text & html versions into separate text documents - e.g ContributionOnlineHTMLDefault.txt & ContributionOnlineHTMLText.txt. Then put the customised versions from the Edit tab into separate documents e.g ContributionOnlineHTMLCustom.txt & ContributionOnlineTEXTCustom.txt
![](https://wiki.civicrm.org/confluence/download/attachments/135135258/CopyCustomisedText.jpg?version=1&modificationDate=1399945725000&api=v2)
Select the files to compare in kdiff (I didn't click merge but I think it is better to as it creates the merged copy down the bottom)
![](https://wiki.civicrm.org/confluence/download/attachments/135135258/Compare2FilesInKdiff.jpg?version=1&modificationDate=1399945725000&api=v2)
You then get this view - you can see here I loaded the default on the left & the custom on the right - I can scroll up & down the changes using the blue arrow buttons. When I have a change highlighted I choose 'A' to choose side A, B to choose side B. The merged version shows up down the bottom & you can copy this back into CiviCRM & test
![](https://wiki.civicrm.org/confluence/download/attachments/135135258/Compare%26Merge.jpg?version=1&modificationDate=1399945725000&api=v2)
View
@@ -1,65 +1,47 @@
# Upgrading CiviCRM for Joomla
!!! note "Version 4.7 Requirements"
Use this document to upgrade CiviCRM installations on Joomla to the latest CiviCRM release.
**Before beginning this upgrade, verify that your server meets the requirements for CiviCRM 4.7.**
!!! caution "Before upgrading"
Make sure you have done the steps listed in ["Before upgrading"](/upgrade/index.md#before-upgrading) first.
* **Joomla Version.** : CiviCRM 4.7 has been built to run under Joomla 2.5.x or 3.x.x. **4.7** **is not compatible with Joomla 1.0.x and Joomla 1.5.x sites**.
**PHP:** See [CiviCRM PHP Requirements](https://wiki.civicrm.org/confluence/display/CRMDOC/CiviCRM+PHP+Requirements)
* **PHP memory_limit** set to between 256 and 512 megabytes.
* **MySQL 5.1.x or higher with INNODB support** : CiviCRM is compatible the current [generally available MySQL release](http://dev.mysql.com/downloads/mysql). Note that MySQL 5.1 is recommended for new installations and as sites are upgraded as CiviCRM is beginning to use Triggers more (eg to support multi-lingual installations), which require SUPER privileges in MySQL 5.0.
Configuration variable thread_stack >= 192k.
* **PCRE with Unicode properties support** ([more info](http://forum.civicrm.org/index.php/topic,9316.0.html)).
## Download the latest code
!!! danger "Upgrade a Copy of Your Site First and Make a Complete Backup"
1. Go to [civicrm.org/download](https://civicrm.org/download)
1. Select the latest currently available CiviCRM tarball for Drupal.
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. Note that not all versions of mysql or phpmyadmin export triggers or stored procedures by default.
Example: `civicrm-4.7.20-joomla.zip`
!!! note
You may notice a file on the named something like `civicrm-4.7.xx-joomla-alt.zip` the `-alt` version does not require `.zip` functions compiled into PHP by your hosting company. If you get errors like _"Your PHP version is missing zip functionality"_, then try the `-alt` version.
The steps below assume you are already running Joomla 3.x. If you have not yet upgraded to 3.x, you must do that before installing CiviCRM v4.x. Also note that if you used the jUpgrade extension to manage your Joomla upgrade, it would have created your upgraded site in a subdirectory (jupgrade/ by default). If you use that subdirectory site to upgrade CiviCRM you will need to alter your civicrm.settings.php file prior to the upgrade (to reflect the subdirectory) and after you complete the upgrade and move your site to a root directory (to again reflect the correct directory location).
1. Save this file in `<joomla_root>/tmp/`. Unzipping will create a directory called: `com_civicrm`.
## Download and Un-tar CiviCRM Code
If using localization, also download the latest version of the localization files. See the [CiviCRM Localisation](http://wiki.civicrm.org/confluence/display/CRMDOC40/CiviCRM+Localisation) page about how to install files for running CiviCRM in languages other than American English.
All CiviCRM code and packages used by CiviCRM (such as PEAR libraries) are included in the compressed CiviCRM distribution files ('tarballs'). Follow these steps to download and install the codebase:
## Backup your settings files
* Download the [appropriate archive file](http://sourceforge.net/projects/civicrm/files/) with your browser. Archive file-names include the CiviCRM version. For example, **civicrm-4.7.xxx-joomla.zip**.
* You may notice a file on the named something like **civicrm-4.7.xxx-joomla-alt.zip** the -alt version DOES NOT require .zip functions compiled into PHP by your hosting company. If you get errors like "Your PHP version is missing zip functionality. Please ask your system administrator / hosting provider to recompile PHP with zip support." - Try the -alt version.
* Upload this file to your **JOOMLA_ROOT/tmp/**. Unzipping will create a directory called: com_civicrm.
The ["Before upgrading"](/upgrade/index.md#before-upgrading) steps describe steps for backing _everything_ up in case something goes wrong during the upgrade. In addition to this important safeguard, we also need to actually _use_ these two settings files, as they are, during the upgrade:
## Backup your CiviCRM database and settings file
Refer to the [MySQLDump documentation](http://dev.mysql.com/doc/refman/5.1/en/mysqldump.html) or [phpMyAdmin documentation](http://wiki.cihar.com/pma/FAQ_6.4) if you need information on backing up your database. Note that not all versions of mysql or phpmyadmin export triggers or stored procedures by default.
Also make a backup/copy of civicrm settings files:
1. <joomla_root>/components/com_civicrm/civicrm.settings.php and
1. <joomla_root>/administrator/components/com_civicrm/civicrm.settings.php
#### Customizations
If you have customized CiviCRM through PHP/template (tpl)/css overrides or hooks, you will need to update the code to the upgraded version. Depending on the extent and function-critical nature of your customizations, you may want to upgrade your installation in a development environment first where you can review each modified file, bring it current to the new codebase, and thoroughly test before implementing in a live environment.
If you modified any core files, also be prepared to backup and update them to the new release you are implementing.
* `<joomla_root>/components/com_civicrm/civicrm.settings.php`
* `<joomla_root>/administrator/components/com_civicrm/civicrm.settings.php`
Copy these files to a location outside your Joomla project. You will need to restore them after upgrading.
## Install the Extension
* Login to your Joomla Administrator site.
* Go to Extensions » Manage
* Use the **Install from Folder** tab and enter the full path to the un-zipped **com_civicrm** directory, which should be something like **JOOMLA.x_ROOT/tmp/com_civicrm**. If your temp directory is configured correctly you should only need to add "com_civicrm" to the prepopulated path.
* You should see "CiviCRM successfully installed" message.
!!! warning
*If you get the following error when installing or upgrading CiviCRM for Joomla!,* download and use the civicrm-4.7.x-joomla-alt.zip package.
**Your PHP version is missing zip functionality. Please ask your system administrator/hosting provider to recompile PHP with zip support.**
1. Login to your Joomla Administrator site.
1. Go to Extensions » Manage
1. Use the **Install from Folder** tab and enter the full path to the un-zipped **com_civicrm** directory, which should be something like **JOOMLA.x_ROOT/tmp/com_civicrm**. If your temp directory is configured correctly you should only need to add "com_civicrm" to the prepopulated path.
1. You should see "CiviCRM successfully installed" message.
The steps above will install CiviCRM directly on top of your existing installation. If you run into any issues, such as the component not appearing to reflect the new version, you may need to first uninstall the existing version and then install the new version. Uninstalling CiviCRM will remove the component files, but will not impact your database in any way.
## Run the Database Upgrade script
## Clear the file cache
!!! forbidden "Update requiredments"
Support for MySQL versions prior to 5.0 has been discontinued. Delete all cache files in [yoursite]/media/civicrm/templates_c on your server before proceeding with the update script.
Delete all cache files in `<joomla_root>/media/civicrm/templates_c` on your server before proceeding with the update script.
## Upgrade the database
**After the component installation completes click the link to run the database upgrade script.** You may also point your web browser to the following URL (you should already be logged in to Joomla with administrator-level permissions):
@@ -69,19 +51,12 @@ http://<your_joomla_home>/administrator/index.php?option=com_civicrm&task=civicr
You should see an **Upgrade successful** message when the upgrade completes.
* If you receive any errors during the process, please note the exact error message and check for solutions on the community support forum.
* Now click the **Return to CiviCRM home page** link.
* You should be up and running with the latest CiviCRM version. Confirm by checking the version and revision in the page footer. Note that you may need to refresh the browser screen a couple times to clear out your local cache and ensure the layout loads correctly.
* Take some time to browse the CiviCRM features that your organization uses. If you notice unexpected behaviors or error messages, refer to the trouble-shooting section below.
1. If you receive any errors during the process, please note the exact error message and check for solutions on the community support forum.
1. Now click the **Return to CiviCRM home page** link.
1. You should be up and running with the latest CiviCRM version. Confirm by checking the version and revision in the page footer. Note that you may need to refresh the browser screen a couple times to clear out your local cache and ensure the layout loads correctly.
1. Take some time to browse the CiviCRM features that your organization uses. If you notice unexpected behaviors or error messages, refer to the trouble-shooting section below.
## Verify and Update Configuration Settings
If you are running this installation in a different directory from your old site you may need to update the **CiviCRM Resource URL** setting (missing icons and images, as well as problems with javascript functions and stylesheets are all symptoms that this setting needs to be updated).
* Go to **Administer** » **System Settings** » **Resource URLs**
* Refer to the field help on that screen for instructions.
With each new release of CiviCRM there may be new sub-components and configuration settings available. Visit **Administer » System Settings** and review each section to make sure your system is configured as desired. If you uninstalled CiviCRM before installing the new version please be sure to review each setting carefully as it's possible some of your settings were reset to the default options.
## Restore settings file changes
@@ -90,69 +65,6 @@ Review the backup versions of the files below and compare them with the new vers
1. <joomla_root>/components/com_civicrm/civicrm.settings.php
1. <joomla_root>/administrator/components/com_civicrm/civicrm.settings.php
## Update System Workflow Message Templates as Needed
If your organization has modified the default versions of System Workflow message templates, then the changes and bug fixes included in an upgrade will need to be merged with your modified versions. ([learn more ...](https://wiki.civicrm.org/confluence/display/CRMDOC/Updating+System+Workflow+Message+Templates+after+Upgrades+-+method+1+-+kdiff))
## Troubleshooting
### Reset Session
If you are seeing unexpected behavior after completing the upgrade, you may need to reset your session. First log-out of your Administrator session and log back in. This may resolve the issues. If this doesn't help, use this procedure to force a session reset:
1. Temporarily enable CiviCRM debug features:
* Go to **Administer** » **System Settings** » **Debugging and Error Handling**
* Set **Enable Debugging** to Yes and click Save.
1. 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.
```
// Example URL
http://.../administrator/index.php?option=com_civicrm&task=civicrm/admin/setting&reset=1&sessionReset=2
```
1. Clear template cache by adding an additional query string value (&directoryCleanupReset=1)
```
// Example URL
http://.../administrator/index.php?option=com_civicrm&task=civicrm/admin/setting&reset=1&directoryCleanup=1
```
1. Now set **Enable Debugging** to No and click Save.
!!! danger "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.
### Upgrade script fails with fatal database-related errors OR reports "Database check failed"
Download and run the [Database Troubleshooting Tools](https://wiki.civicrm.org/confluence/display/CRMDOC41/Database+Troubleshooting+Tools) to test the current state of the database and provides a diagnosis. The tools suite also includes a repair facility.
(Note ... the troubleshooting tools do not work with version 4.7 - this item should be deleted shortly)
### Remove cached copies of old templates
It may be that the install did not clear out the template cache. Try removing the cache contents. For example, with Linux, use with a command like:
```
rm -r JOOMLA_ROOT/media/civicrm/templates_c/en_us/en_us
```
This will force CiviCRM to load the new templates rather than cached copies of the old ones.
### Out of Date Joomla! Version
!!! forbidden "Joomla 2.5 reached End of Life (EOL)"
* **Joomla 2.5 reached _End of Life_ (EOL) in 2014 and is no longer supported by the Joomla! Project.**
* **While CiviCRM 4.7 supports Joomla 2.5.x or 3.x.x, i**** t is strongly recommended by the Joomla! Project that 2.5 users upgrade to the most current version of 3.x ([https://docs.joomla.org/Joomla!_CMS_versions](https://docs.joomla.org/Joomla!_CMS_versions)).**
### Cron Job Reconfiguration Necessary when upgrading from < CiviCRM 4.2
!!! danger "System Administrators Alert"
**All Cron Jobs Must be Re-configured**
* **Upgrades from 4.1.x and prior: All CiviCRM-related cron jobs will stop working as soon as any site is upgraded from 4.1.x and below**. If you are upgrading from a version prior to 4.2, cron jobs will need to be reconfigured using the new [Scheduled Jobs](http://wiki.civicrm.org/confluence/display/CRMDOC43/Managing+Scheduled+Jobs) method.
* **Upgrades from 4.2.x** : If you are running scheduled jobs using CLI.php, you will need to reconfigure cron to include a password. Scheduled jobs will no longer run if the password is not provided ([learn more](http://wiki.civicrm.org/confluence/display/CRMDOC43/Managing+Scheduled+Jobs)).
### Need More Help?
## Post upgrade
If you have any problems with these procedures, try searching the [community forums](http://forum.civicrm.org/) and this wiki for solutions. If you've gotten an error message, use that message in your search. If you can not resolve the problem, then post your problem to the forum. Be sure to include the CiviCRM version and revision you are upgrading FROM and TO; your Joomla version; your PHP and MySQL versions; the steps you've taken and a the exact error message or problem that resulted.
See these steps to take [after upgrading](/upgrade/index.md#after-upgrading).
Oops, something went wrong.

0 comments on commit fb662ea

Please sign in to comment.