WordPress Installation Guide for CiviCRM 4.1

Install process for CiviCRM 4.1 on WordPress IMPORTANT: CiviCRM 4.1 requires WordPress 3.3.x. This page provides instructions for installing CiviCRM as a plugin for WordPress. This is the recommended installation method. Before beginning the install process, please verify that your server meets all the requirements for CiviCRM 4.1. WordPress 3.3.x : CiviCRM 4.1 is built to run under WordPress 3.3.x and is not compatible with earlier WordPress versions. PHP 5.2.1+ : CiviCRM 4.1 is compatible with PHP 5.3. (more info...). MySQL 5.1.x or higher with INNODB support : CiviCRM is compatible with the current generally available MySQL release. Trigger permission is required to enable logging and multi-lingual support. SUPER privileges are required in MySQL 5.1 if binary logging is enabled. PCRE with Unicode properties support (more info). MAMP XCache in-compatibility* - Several people have reported "white screen of death" trying to run CiviCRM 4 with MAMP's XCache enabled (check MAMP > Preferences > PHP > Cache).

1. Server Requirements

CiviCRM for WordPress has been developed and tested by our team on the following 'recommended' platforms:

• Linux
• Apache 2.1
• PHP 5.2.x (or newer)
• MySQL 5.1+ with INNODB enabled
• WordPress 3.3.x

Plugin Issues

Because of the huge number and ever-changing nature of community contributed Wordpress plugins, CiviCRM cannot guarantee compatibility with all contributed plugins.  Wordpress+CiviCRM is known to be incompatible with the following Wordpress plugins:

• Facebook Like Thumbnail

2. WordPress Installed

Before installing CiviCRM you need to have a working site with WordPress 3.3.x. If you do not have the required version of WordPress installed, refer to:

• WordPress Installation Guide

  Path for WordPress The rest of these instructions assume that you have WordPress installed in /var/www/wordpress. Adjust paths as needed.

3. Download and Un-zip CiviCRM Code

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:

• Download the appropriate tarball file from here with your browser. Tarball file-names include the CiviCRM version. For example, civicrm-4.1.x-wordpress.zip.

• Copy or ftp the tarball file to your WordPress installation's /wp-content/plugins directory. You may have to change the "File Permissions" setting of /wp-content/plugins/civicrm directory to allow for "Write" Access. Just remember to change it back to default when done.

• Create the <wordpress path>/wp-content/plugins/files/ directory and ensure it is writable. CiviCRM uses this directory for temporary and uploaded files.

Downloading Directly to Your Server with wget If you have command-line access, you may prefer to download the tarball file directly to your server using wget:

* Un-tar (unpack) the codebase into the wordpress/wp-content/plugins directory.

* You should now have a /var/www/wordpress/wp-content/plugins/civicrm directory containing civicrm.php, README.txt and another civicrm directory (which in turn contains bin, CRM, sql, templates, etc.).

4. If Using Localization, Download and Un-tar the Localization Files

Follow these steps to download and install the files that contain strings for languages other than American English:

• Download the appropriate tarball file from here with your browser. Tarball file-names include the CiviCRM version, and l10n (that's lower case ell-ten-en). For example, civicrm-4.1.x-l10n.tar.gz..

• Copy or ftp the tarball file to your WordPress installation's /wp-content/plugins directory. You may have to change the "File Permissions" setting of /wp-content/plugins directory to allow for "Write" Access. Just remember to change it back to default when done.

Downloading Directly to Your Server with wget If you have command-line access, you may prefer to download the tarball file directly to your server using wget:

* Un-tar (unpack) the language files into the wordpress/wp-content/plugins directory.

* You should now have a wordpress/wp-content/plugins/civicrm/civicrm/l10n directory with a number of directories below it (including bin, CRM, sql and templates).

5. Enable CiviCRM plugin and run installer

The installer will verify that you've downloaded the correct version of CiviCRM, and will check your server environment to make sure it meets CiviCRM requirements. It will then create and populate a database for CiviCRM as well as create your CiviCRM settings file (civicrm.settings.php).

• Login to your WordPress site with Administrator level permissions.
• Go to plugins page: http://<your_wordpress_home>/wp-admin/plugins.php.
• Click the 'Activate' link to activate the CiviCRM plugin.
• Then go to Settings > CiviCRM Settings: http://<your_wordpress_home>/wp-admin/options-general.php?page=civicrm-settings

• You should see the CiviCRM Installerscreen.
  • Initially, you will see a red bar with the message "These database details don't appear to be correct." This is expected as you haven't entered your database settings yet.
  • If you see other errors, check the Requirements details at the bottom of the page for more information. You will need to correct any issues before continuing.

• Fill in the CiviCRM Database Settings.

  Where Should I Store CiviCRM Data? CiviCRM may be configured to use your existing WordPress database, or a separate (new) database. Using a separate database is generally preferred - as it makes backups and upgrades easier. The installer will create a new database for CiviCRM automatically if you enter a database name that doesn't already exist on your database server AND the database user you enter has permission to create databases. In case the installer does not automatically create a new database, simply create a new one following the same process as creating a new database for WordPress.

• Fill in the WordPress Database Settings for your existing WordPress database (as noted in step 2 above).

  Loading Sample Data The Installer includes an option to load a set of sample contact, group, and relationship data by default. Sample data can provide a useful head-start in learning to use CiviCRM. However, if you do NOT want the sample data to be loaded, just uncheck Load sample data under Other Settings.

• Select the appropriate language for the base installation. You will be able to add other languages after the installation for multi-lingual sites.
• Click the Check Requirements and Install CiviCRMbutton.
  • The installer will configure your databases, create the settings file and will redirect to success message.
  • If you still see a red bar with the message "These database details don't appear to be correct." - check the Database Details section below your settings for specific errors and problems. Once you correct these problems, click "Recheck requirements" to verify your settings before continuing.
  • If you are on a Windows machine and get the message "The user account used by your web-server needs to be granted write access to the following directory in order to configure the CiviCRM settings file:
    C:<wordpress path>/wp-content/plugins/civicrm/" even after changing directory permission in Explorer, see http://forum.civicrm.org/index.php/topic,5056.msg23720.html#msg23720 for instructions how to change the permissions using CMD.
  • Once you see the green "You're ready to install!" message - you can click Check Requirements and Install CiviCRM

6. Locate and Backup the CiviCRM settings file

After installation, a configuration file will have been created by CiviCRM at: <wordpress>/wp-content/plugins/civicrm/civicrm.settings.php

It is critical you make a copy of this file and save as a backup in a safe location. This file contains passwords and other critical information, take precautions to secure the copy from prying eyes.

Should an upgrade fail, you will need this backup copy to restore your site.

7. Create CiviCRM Contacts for Existing WordPress Users

Once installed, CiviCRM keeps your WordPress Users synchronized with corresponding CiviCRM contact records. The 'rule' is that there will be a matched contact record for each WordPress user record. Conversely, only contacts who are authenticated users of your site will have corresponding WordPress user records.

When CiviCRM is installed on top of an existing WordPress site, a special CiviCRM Administrative feature allows you to automatically create CiviCRM contacts for all existing WordPress users:

• Login to your WordPress site with an administrator-level login
• Click the CiviCRM link in the main navigation block
• Click Administer CiviCRM
• If your WordPress site makes use of the db_prefix setting (in settings.php - cf. Step 2, above), click Configure Global Settings, then WordPress Integration Settings, and update the box for the WordPress Users Table Name so that it includes the prefix.

8. Review the Configuration Checklist

The Configuration Checklist provides a convenient way to work through the settings that need to be reviewed and configured for a new site. You can link to this checklist from the installation success page AND you can visit it at any time from Administer CiviCRM » Configure » Configuration Checklist.

9. Test-drive CiviCRM

There should now be a CiviCRM link in your WordPress menu. Click that link and the CiviCRM Menu, Shortcuts, Search and New Individual Blocks should appear.

You can now explore CiviCRM end-user features and begin configuring CiviCRM for your site/organization needs. Refer to the Administrator Guide for information on configuration tasks and options. Tips for creating CiviCRM Profiles (forms), custom data fields and programming custom data manipulation are included in the Drupal installation and configuration example document.

10. Upgrade CiviCRM

When a new, stable version of CiviCRM is released it is recommended you upgrade if the release contains security patches, bug fixes or new features you desire.

1. Backup your existing <wordpress>/wp-content/plugins/civicrm directory by creating an archive or FTPing it to your local computer
2. Backup your existing database through Control Panel or PHPMyAdmin
3. Download the latest CiviCRM .zip package from the download link at CiviCRM.org
4. Upload the .zip file to: <wordpress>/wp-content/plugins
5. Use your Control Panel to "extract" or "unzip" the file careful to:
  a. make sure you have a backup of your civicrm.settings.php file (see above at heading #6)
  b. you overwrite existing civicrm directory during the extraction/unzip
  c. do NOT create an additonal subdirectory for the extraction
6. Run the Upgrade script at:http://www.YOURSITE.org/wp-admin/admin.php?page=CiviCRM&q=civicrm/upgrade&reset=1

Trouble-shooting Resources

Review the Installation and Configuration Trouble-shooting section of our wiki for help with problems you may encounter during the installation.

You can often find solutions to your issue by searching the installation support section of the community forum and you can check out the Installation section of our FAQs.

If you don't find an answer to your problem in those places, the next step is to post a support request on the forum.