Using CiviCRM（Second Edition）
上QQ阅读APP看书，第一时间看更新
上一章目录下一章

Installing CiviCRM

We've got a handle on what CiviCRM does, we've mapped out our system, and then planned our implementation; now let's get things up and running!

Note

The following instructions assume that you have a working installation of Joomla!, Drupal, or WordPress. If you have not yet set up your CMS environment, you should do so before continuing with this section.

Begin by visiting the CiviCRM website, http://civicrm.org/download, or going directly to http://sourceforge.net/projects/civicrm/files/ to select a version of CiviCRM to install. We always recommend using a stable version for production sites. For the browser-based methods of installing (using the CMS extension installer), you need to download the installation package onto your local machine, and then upload it to your server. The advanced command-line installation method discussed for Drupal allows you to skip this step by retrieving the package directly to your server.

Note

You may note multiple recent major version releases listed toward the top of the release page in Sourceforge. This is because in recent years, CiviCRM has introduced the idea of a Long Term Support (LTS) release, in addition to the ongoing stable releases. Largely supported by the community, the idea is to support critical bug fix and security issues in a selected release for longer than usual. In general, once CiviCRM moves to a new stable release, support for the previous version ceases. The LTS model extends support for that particular version through subsequent new stable versions. For example, currently, v7.66.10\ is the current stable release and v4.6.154.4.20 is the most recent LTS release. Typically, every other version is selected for LTS.

Be sure to always visit the download site when implementing a new installation of CiviCRM, as the project releases minor revisions on a regular basis. Decide whether you want to stay with the latest version and have all the latest functionality, or if you would like a more defensive release policy and plan for upgrades to the latest LTS versions.

Note

When you visit the download page, take the time to read the information about becoming a supporter of the project through membership. Although CiviCRM is free to download and install, it is not free to develop and support. Your membership helps ensure the ongoing sustainability of the project.

There are several installation packages available for CiviCRM, depending on your environment. Let's review them briefly:

  • Drupal: This package is a standard package for Drupal 7 installations.
  • Drupal 6: This package is a standard package for Drupal 6 installations.
  • Joomla!: This package is a standard package for Joomla! 3.x installations.
  • Joomla-alt: This package is an alternate package for Joomla! 3.x installations. This package differs from the standard package in that it does not include embedded compressed files. If you were to examine the standard Joomla! installation package, you would find that it contains a series of installation files and a large .zip package. In contrast, unpacking the -alt version shows all the application files (that is, there is no subpackage inside the main package). Generally, the standard package will work for most installations. But if you have problems, you might try using the -alt version, as it is larger, but requires less resources to install.
  • WordPress: This package is a standard package for the WordPress installations.

In addition to the preceding versions, you will also see a language package file (-l10n) and MD5 hash files (MD5SUMS), which can be used to verify the package integrity.

CiviCRM has a strong multilanguage support. The language package contains translation files for all the languages supported in the current version of CiviCRM.

Note that some of these translations are not complete and should be reviewed and tested thoroughly before implementing in a live environment. Generally, the strings in public user-facing pages are translated first, with administration strings and rarely-used functionality lagging.

In some cases, you may find that you can combine existing language resource files for different regions to extend their coverage. For example, separate translation efforts for Canadian French and French in France were combined into a new Canadian French file that used Canadian terms when there were translations available in both language files. This allowed State/Province to be rendered as Province, rather than Department.

For more details on CiviCRM's translation and localization efforts, visit the following links:

To view the status of any translation, visit the translation tool referenced in the preceding list, where details about the percentage completion and number of text strings yet to be translated are reported.

There are translation teams for Arabic, Bosnian, Catalan, English (Canadian), Norwegian Bokmål, Persian, Tamil, and Ukrainian. This usually means that a translation was produced for that language in an earlier version, which is likely to provide some useful materials for a new translation. If multilanguage support is something you are interested in, consider participating in translations using the preceding tools.

Tip

Before proceeding, ensure that your hosting environment meets the minimum requirements, as outlined in the previous chapter. Though you may have success installing CiviCRM in an environment that does not meet those base technical requirements, you are likely to find that certain functions do not work correctly if those requirements are not met.

CiviCRM maintains a current list of requirements and installation/upgrade guidance on the CiviCRM Wiki at http://wiki.civicrm.org/confluence/display/CRMDOC/Installation+and+Upgrades. We will walk through the basic installation process for all the three CMS environments that are covered in the next section. If you run into difficulties or need more detail, visit the preceding Wiki page.

Installation in Joomla!

CiviCRM is installed using Joomla!'s extension installation tool, available at Extensions | Manage in your Joomla! website's administrative interface. However, unlike most Joomla! extensions, you may not be able to install the software using the Upload Package File option because CiviCRM is a very large piece of software—over twice the size of Joomla! itself. Most hosting environments are not configured to accommodate the resources required to upload the package and run the installation script in a single process. You may certainly try installing the traditional way, but if your browser times out or you experience other issues, you will need to use the alternative method, which we will detail in this section: Install from Folder.

Tip

Follow the installation instructions carefully, as they differ from the installation process for many other Joomla! extensions.

Proceed with the following steps to install CiviCRM in Joomla! using the Install from Folder method:

  1. Upload the installation package to your website using the FTP software. We recommend that you upload the package to /YOUR_JOOMLA_ROOT/tmp/. This folder is created by Joomla!, and is the most appropriate place to store installation packages prior to installation.
  2. Unpack the installation package. You may do this using the command line or a web-based file browser hosted on your server (such as cPanel File Manager). There are various extensions available for Joomla! that let you work with the filesystem from within Joomla!, which may also be helpful. If you have difficulty unpacking the installation package online, you may need to unpack it on your local computer and use the FTP software to upload the unpacked set of files to /YOUR_JOOMLA_ROOT/tmp/. After uploading and unpacking, you should see /com_civicrm/ inside /YOUR_JOOMLA_ROOT/tmp/.
  3. Browse to Extensions | Manage in the Joomla! administrative interface and click on the Install from Folder tab. Enter the full file location of the unpacked /com_civicrm/ directory. In most cases, Joomla! will prefill that field with the proper location of /YOUR_JOOMLA_ROOT/tmp/ and you will only need to add com_civicrm.
  4. After clicking on Install, you should be directed to a screen, confirming a successful installation. Click on the link provided to enter CiviCRM and confirm that it is installed and working.

Tip

Upgrading will be discussed later in this chapter, but while we are here, note that upgrading CiviCRM in Joomla! will happen exactly as described in the preceding steps, except that after the installation, you will be presented with a link to trigger the database updates pertaining to that upgrade version. It is critical that you run this script or your codebase will not be in sync with your database. Be sure to backup your database before doing so in case there are problems and you need to revert.

If you experience problems installing CiviCRM, review the Installation troubleshooting section for a general review of possible server and environment-related issues. With the Joomla! installation, the most common problem arises from unfamiliarity with the Install from Folder method we just described. Most Joomla! users are used to the more common Upload Package File method of installing extensions.

Two critical things to remember are as follows:

  • The CiviCRM installation package must be unpacked on the server. You should be referencing a folder location, and not the .zip file you downloaded from www.civicrm.org.
  • The folder location must be the full filesystem path, and not the path relative to your web directory. For example, it may look something like /home/user/public_html/tmp/com_civicrm/. If you received the error message, Please enter a package directory, it is because you are not referencing the correct path to the unpacked installation files.

If you continue to experience problems during installation, search CiviCRM's StackExchange site (http://civicrm.stackexchange.com/) to look for existing answers or ask a new question.

Installing in Drupal 7

CiviCRM uses an automated installer to configure the software for use in Drupal. The directions that follow address setting up an implementation of CiviCRM within your existing Drupal installation.

As most Drupal developers will know, Drupal supports using a single codebase to operate multiple websites (see https://www.drupal.org/documentation/install/multi-site). Site-specific data is stored in site-specific directories under /path_to_docroot/sites/, with each site's domain name typically used as the name of its subdirectory. This site-specific information includes the database name unique to each site and other connection information stored in the /path_to_docroot/sites/yoursite.org/settings.php file. CiviCRM supports this multisite shared codebase and separate databases approach transparently during the installation process. If you are using a multisite environment, make sure to create a separate CiviCRM database for each site before starting its installation process.

Although this multisite approach is still very popular, there are some countervailing trends in favor of single site installs. There are dependency, complexity, and timing issues, when attempting to upgrade multiple sites sharing a codebase in a single directory simultaneously. More importantly, Drush ( (http://community.aegirproject.org/) have made it increasingly easier to manage a single codebase for multiple single site installs using multiple copies of the same code files.

The CiviCRM installation procedures in the following sections work if your Drupal site is either a single-site or a multiple-site configuration, as we just described. Different procedures are required if you want to use advanced techniques for sharing database tables between different Drupal sites in order to provide a single sign-on capability or for sharing a database across several CiviCRM sites in order to share contacts and/or administrators between sites (visit http://wiki.civicrm.org/confluence/display/CRMDOC/Multi+Site+Installation).

Depending on your skill and comfort level, you can choose to install CiviCRM in different ways. The first one uses a browser and a client application for FTP. The second one uses SSH, a secure command-line shell, and may be faster and more convenient for those with basic Linux skills.

Browser/FTP procedure

Before you begin the installation process, take a note of the database settings for your Drupal installation. If you do not know the values, you can view them at /path_to_docroot/sites/default/settings.php (the default location).

Locate the $db_url variable:

$db_url = 'mysqli://dbuser:dbpassword@localhost/drupal_dbname';

The database connection elements are as follows:

  • Database server: localhost
  • Drupal database name: drupal_dbname
  • Database user name: dbuser
  • Database user password: dbpassword

Note

Note that older sites may still be using the mysql driver, rather than mysqli.

If this includes your site, you should definitely consider upgrading to mysqli, as it provides performance improvements over the mysql driver. Changing the driver specification from mysql to mysqli in the $db_url variable is all that is required for Drupal to gain these benefits.

You may now begin the installation process. Follow these steps:

  1. If you haven't done so already, download the latest stable CiviCRM installation tarball for Drupal to your local machine from http://sourceforge.net/projects/civicrm/files/ (using the Download Now! button is the best way to ensure you get the right tarball).
  2. Upload the CiviCRM installation package from your local machine to /path_to_docroot/sites/all/modules/ in your Drupal installation. Installing CiviCRM and other modules under this directory will keep the files separate from core Drupal modules and facilitate any future Drupal core upgrades. If you don't want CiviCRM to be available to other sites running off this codebase, you can create a modules subdirectory under your sites directory at /path_to_docroot/sites/default or /path_to_docroot/sites/yourdomain.org and install it there instead. If necessary, adjust the permissions for /path_to_docroot/sites/ to provide write access to the account that is running the web server process (and return it to the original permissions when complete). This can normally be done using your FTP or SFTP client applications, or by using the following command: 
    $ cd /path_to_docroot/sites/ ; chmod –R 666 ./*
  3. Unpack the installation package. You should now have the following directory in your site: /path_to_docroot/sites/all/modules/civicrm/, with other subdirectories contained within it.
  4. Create a separate MySQL database for CiviCRM using an appropriate tool such as phpMyAdmin or your hosting panel. The installer will create a new database for CiviCRM automatically if you enter a database name in the next step that doesn't already exist on your database server, and the database user you enter has permission to create databases. We don't recommend granting that privilege to database accounts that don't need it, such as the ones used by your Drupal site.

    Note

    Although not required, we find it to be good practice to keep Drupal and CiviCRM in separate databases for backup and upgrade purposes. Consider using a naming convention where the domain name is used for the database username, and _dru and _civ are appended to the databases to indicate Drupal and CiviCRM.

    Note that if you plan to use the Drupal Views module to display CiviCRM data within your Drupal pages, and if you are going to use separate database users for Drupal and CiviCRM, you need to ensure that your Drupal database user has the SELECT permissions for your CiviCRM database. Using the same database user for both Drupal and CiviCRM as described meets this requirement.

  5. The next step is to run the installer, which will confirm that you've downloaded the correct version of CiviCRM and ensure that your server meets the software requirements. The installer creates the necessary tables in your database and configures the civicrm.settings.php file with the required variables. To run the installer, log into Drupal as a user with administrator permissions and point your browser to the following URL: http://yourdomain.org/sites/all/modules/civicrm/install/index.php.
  6. This opens the CiviCRM installation tool. Complete the form with the database details you noted down earlier for the Drupal database and the ones you created for your CiviCRM database, and then click on it to recheck the configuration and requirements. If there are any system settings that do not meet the requirements, you will be given a notification and a chance to resolve the issues. Return to this page and recheck until you have all the issues resolved. You may also choose to install sample data (which provides a good head start to understanding the system) and select an alternate language (if you've obtained and uploaded the translation files to the CiviCRM directory).
  7. Click on the Check Requirements and Install CiviCRM button to proceed with the installation. If the installation script completes successfully, you will receive a green bar and a notification of success. During the installation, CiviCRM configures standard permissions for anonymous and authenticated users to access the CiviCRM tools and forms. You will want to review these settings to confirm that they suit your website's needs. We will discuss the Drupal roles and permissions as they relate to CiviCRM later in this book.

    Note

    Note that during installation, Drupal creates a files directory underneath /path_to_docroot/sites/ for your site and makes it writeable. CiviCRM will create folders for temporary files under this directory by default, for example, /path_to_docroot/sites/yoursite.org/files/civicrm.

  8. The installation script will enable the CiviCRM module automatically. If the module is enabled, you should now have a link in your menu for CiviCRM. Click on the CiviCRM menu item to enter and confirm a successful installation.
  9. If you don't see the CiviCRM link on your primary menu when logged in as an administrator, browse to Modules to confirm that the CiviCRM module is enabled. If the module is enabled and you still can't see the CiviCRM link, visit the CiviCRM StackExchange site to search for answers or ask a new question (http://civicrm.stackexchange.com/).

Drupal shell procedure

The Drupal shell (Drush) procedure is a Linux shell utility, which can be used to perform actions on your Drupal installation, including multisite management. CiviCRM provides several commands that can be used with Drush to manage your site. Before using it, you must install Drush and the CiviCRM support file (detailed in this section). Details on installing Drush can be found at are as follows:

After you installed Drush and confirmed that it's working, you can proceed to use it to install CiviCRM:

  1. If it doesn't already exist, create a directory for your Drupal modules either at /path_to_docroot/sites/all/modules (recommended) or in the directory for this site (for example, /path_to_docroot/sites/yourdomain.org/modules) to prevent CiviCRM from being available to other sites running off this codebase: 
    $ mkdir –p /path_to_docroot/sites/all/modules
  2. Locate the tarball to be installed by navigating in your browser to http://sourceforge.net/projects/civicrm/files/ and choosing the correct version to use in the following command in the place of VERSION (note that the version number appears twice in the URL): 
    $ wget -O /path_to_docroot/sites/all/modules/civicrm.tar.gz

    Refer to http://downloads.sourceforge.net/project/civicrm/civicrm-stable/VERSION/civicrm-VERSION-drupal.tar.gz.

  3. Unpack the tar file in order to make the CiviCRM Drush commands available: 
    $ tar –xvf /path_to_docroot/sites/all/modules/civicrm.tar.gz

    Refer to http://downloads.sourceforge.net/project/civicrm/civicrm-stable/VERSION/civicrm-VERSION-drupal.tar.gz.

  4. Now, install CiviCRM with Drush using the following command, substituting appropriate values for yourDbUser, localhost, yourCivicrmDbName, and VERSION: 
    $ drush civicrm-install --dbuser=yourDbUser --dbpass=yourDbPassword --dbhost=localhost --dbname=yourCivicrmDbName --tarfile=sites/all/modules/civicrm-VERSION-drupal.tar.gz --destination=sites/all/modules
  5. In a browser, log into your site as a Drupal administrator.
  6. Browse to Modules to confirm that the CiviCRM module is enabled.
  7. You should now have a link in your menu for CiviCRM. Click on the CiviCRM menu item to enter and confirm a successful installation.

If you don't see the CiviCRM link in your primary menu when the CiviCRM module is enabled, visit the CiviCRM StackExchange site to search for answers or ask a new question (http://civicrm.stackexchange.com/).

Installation in Drupal 6 is almost identical to what is described in the preceding steps. See the Wiki document reference earlier in this chapter for more details.

Installing in WordPress

It under Drupal: http://forum.civicrm.org/index.php/board,6.0.html.

Begin by downloading the most recent version from the CiviCRM download page (SourceForge) cited earlier. Then, follow these instructions for installing CiviCRM:

  1. Upload the .zip package to your WordPress installation's /wp-content/plugins/ directory and extract (unzip) the package. This should result in a new civicrm directory.

    Tip

    If you are comfortable working in the command line, you can use wget to transfer the package from SourceForge directly to your website, and then unpack it.

  2. Create /wp-content/plugins/files, which will be used by CiviCRM to store temporary and uploaded files.
  3. Log in to WordPress with administrator level access and visit the Plugins page. Locate CiviCRM and activate it.
  4. Visit Settings | CiviCRM Installer, which should direct you to the CiviCRM installation/configuration tool. Initially, you will see a red bar, indicating the database details are not correct. This is expected, as you've not yet filled in the configuration options. Fill in the database details for CiviCRM and WordPress, and then click to recheck the configuration settings. You may also optionally choose to install sample data, which can be helpful to get you up and running with the system.
  5. Once you receive the green You're ready to install message, you can proceed with the installation.
  6. After successful installation, back up the civicrm.settings.php file that was created in /wp-content/plugins/civicrm/. You will need to access this in the future when you perform upgrades.
  7. In step 4, you need to enter the details for both your WordPress database and CiviCRM database. These could be the same database, or separate ones. In general, most developers prefer keeping the databases separate as it facilitates backups and the upgrade process. However, it also means you have multiple databases to maintain and manage. Consider the pros and cons of both configurations as you walk through the installation process.

Installing troubleshooting

A majority of installation problems are the result of a failure to meet the hosting server requirements, insufficient resources in your hosting environment, or misunderstanding of the installation steps detailed in the previous section. Let's review each of these steps.

As noted earlier, CiviCRM does have specific requirements for the hosting environment, which include the versions of Apache/MySQL/PHP used, InnoDB support for MySQL, and certain PHP extensions required for various functions. In some cases, CiviCRM will render an error along with guidance when you attempt to install the software without meeting the base requirements. However, at times you may be able to install CiviCRM without the presence of descriptive errors and may not notice issues until later. Be sure to review and confirm compliance with the server requirements prior to installation.

If you are unsure what versions of Apache/MySQL/PHP your hosting environment is running, create a file named phpinfo.php in your document root directory, containing only <?php phpinfo(); ?>. Ensure that it is readable by your web server, and then navigate to http://yoursite.org/phpinfo.php. In Joomla!, this information can be reviewed through System | System Information without the need for a separate phpinfo file. After creating a phpinfo.php file and reviewing your system details, delete the file from your web server as it presents a certain security risk by exposing system details.

The second common cause for installation problems is inadequate hosting resources. CiviCRM is a fairly resource-intensive application, and your ability to install and work within the system will be directly related to the resources available on your web host. For this reason, we strongly recommend running your CiviCRM installation on a virtual private server, cloud server where you have control over resource levels and configuration, or dedicated hosting. While it may be possible to run CiviCRM on a shared hosting environment, it will be more susceptible to resource-related problems.

Insufficient resources often result in the dreaded white screen of death. If you have carefully followed the installation steps outlined in the preceding steps, and after completing the installation have received a white screen, it's likely you lacked sufficient resources to complete the installation script.

Tip

Insufficient memory may manifest in a number of other ways during an operation as well, such as explicit errors about insufficient memory and occasionally odd PHP error messages while doing memory-intensive operations. Unless you have tuned your Apache, or other web server, settings after increasing your PHP memory settings, insufficient CPU resources often manifest as insufficient memory. If Apache has been tuned to ensure that it does not spawn too many processes, insufficient CPU resources will result in users seeing timeouts on their page requests. Insufficient disk space manifests first as a slowdown in server responsiveness before the users start seeing errors about temporary files not being saved correctly.

The solution? Well, really the best solution is to look at moving your site to a new hosting environment better suited to CiviCRM. While it may be possible to install CiviCRM through a manual process, resource issues during installation are a good indication that you will experience other resource-related problems when actually working within CiviCRM.

Tip

The CiviCRM website maintains a community-contributed list of hosting providers and comments about how CiviCRM runs in their environment. If you've not yet chosen a hosting solution, review this page to help with your selection process: at http://civicrm.org/experts.

Sometimes, the insufficient resources are due to the PHP settings and not the actual resources available on the hosting space. We recommend the following minimum settings, which can be altered through your .htaccess or php.ini file, depending on your server configuration. Refer to your hosting documentation for details on the preferred method for altering these settings, and to confirm that they will permit such modifications. Also note that these recommendations represent a standard minimum level—the size of your database, number of concurrent users, and other load factors may require higher values. Resource-intensive activities, such as large data imports may also require higher values for the temporary periods of time.

.htaccess:
php_value memory_limit 128M
php_value register_globals off
php_value max_execution_time 600

php.ini:
memory_limit = 128M
register_globals = off
max_execution_time = 600

The third common problem is simply a misunderstanding of the installation process. Take time to review the installation steps outlined in the previous section for your respective CMS environment, and ensure you have completed each step accurately. Search StackExchange or the online forums if your installation problems persist.

上一章目录下一章