Install & Configure

Before reading further, please be aware that much of the information contained here is intended for technicians and may be difficult to understand if you have little or no experience in setting up web applications. If you don't understand this topic you may wish to either seek help, or point your organisation's technical staff to this material.

Installation

CiviCRM must be installed on a computer that has been configured with a web-server, PHP, and MySQL. Some people prefer to try out CiviCRM on their own local computer before installing it on a dedicated web-server. If you are doing this and don't have the pre-requisites mentioned above ou can download packages such as Wamp, Xampp, Mampp and Lamp off the internet which will quickly install Apache web-server, PHP and MySQL. (The first two are for Windows and the second two are for Macintosh and Linux respectively).

Once you are ready to start using CiviCRM in your organization you'll probably want CiviCRM to be available on the internet. However, some organizations only want internal staff to have access. In this case they may choose to install CiviCRM on an intranet or internal network.

Before you can begin the installation process, you will need to decide whether you are going to use CiviCRM integrated with Drupal or Joomla, or in standalone mode. Refer to the appropriate section in the online CiviCRM Installation Guide for the latest system requirements and specific installation steps:

http://wiki.civicrm.org/confluence/display/CRMDOC/Installation+and+Upgrades

A Note About Upgrades

New versions of CiviCRM are released two or three times a year - and you will need to apply upgrades to your CiviCRM site periodically in order to take advantage of new features and improvements. It's important that you plan for the resources (people and time) required to apply upgrades to your site. You need to plan on testing upgrades on a copy of your live site to make sure the process runs smoothly. It's critical to make backups of your site and database prior to running an upgrade.

Refer to the appropriate section of the online CiviCRM Installation Guide for specific upgrade procedures. Be sure to select the procedure that is targeted for the environment you are running (Drupal, Joomla or Standalone), and the version you are upgrading to.

For example, if you are looking at the online Installation Guide, refer to Upgrade Joomla Sites to 2.2 if you are running CiviCRM 2.1 with Joomla.

Configuration

Now that you have CiviCRM installed and running on your web-server, it's time to review the initial configuration tasks which allow you to customize CiviCRM for your organization.

You can easily access each of the configuration screens described below from the Configuration Checklist. Login to your CiviCRM site and navigate to Administer CiviCRM » Configure » Configuration Checklist. This section will cover the general tasks, while component-specific configuration will be covered in each component section.

Note : It's helpful to understand the term token before you continue reading this section. Tokens are special blocks of text which refer to a specific field in your database. They are used to control what fields are included in address display and mailing labels, and can also be used to personalize emails. This is described in more detail below. If you've used "mail merge" in your word processor, then you've already used tokens.

CiviCRM uses tokens to control which fields are included in mailing labels and address display, and how they are arranged. Tokens are always surrounded by curly brackets, and include the record type followed by the field name. EXAMPLE: {contact.street_address}. Address values are taken from the contact's primary location.

Tokens are skipped when they refer to a field that is empty for a particular contact.

EXAMPLE: The default Individual Name Format includes {contact.middle_name}. If a contact doesn't have a middle name, that token is skipped.

EXAMPLE: The default Mailing Label format includes {contact.supplemental_address_1} on a separate line. If there is no supplemental address for a particular contact, that entire line is omitted - there will NOT be a blank line in the label.

Localization

Localization involves adapting CiviCRM for use in a specific country or language by translating the text displayed on the screen and setting region specific formats for dates and money (including currency). By default CiviCRM is "localized" for the United States. If you are using CiviCRM in a different country or countries, or you need to store contact addresses in countries other than the United States, or you want to use CiviCRM in another language, you will need to review and update the values on this screen.

CiviCRM has been translated into a number of different languages. These translations are contributed by community members - so your first step is to determine if a complete translation exists for the current version by visiting the Translation Server home page at http://translations.civicrm.org/. If you find a completed translation, you can download it and select it on this screen. Otherwise you will need to consider whether you have resources for contributing a translation.

It is also possible to configure your site to support multiple languages. In this mode, your users will be able to choose from a list of available languages after logging in. You can also create and store multi-language versions of text that is added by your users. Examples include custom field labels, online contribution page, campaign information, and event descriptions.

Further reading:
Localization overview - http://wiki.civicrm.org/confluence/display/CRMDOC/CiviCRM+Localisation

Domain Information

Use this screen to enter identifying information for the organization or entity which "owns" this CiviCRM installation. The organization name and address are used to identify your organization in CiviMail mailings (when you include the domain.name and domain.address tokens).

You should also enter a valid email address that belongs to your organization which will be used as the FROM email in system-generated (automated) emails.

Viewing and Editing Contacts

This screen allows you to modify the screen and form elements for the following tasks:

• Viewing Contacts - Control the tabs that should be displayed when viewing a contact record. EXAMPLE: If your organization does not keep track of 'Relationships', then un-check this option to simplify the screen display. Tabs for Contributions, Pledges, Memberships, Events, Grants and Cases are also hidden if the corresponding component is not enabled
• Editing Contacts - Control the sections that should be included when adding or editing a contact record. EXAMPLE: If your organization does not record Gender and Birth Date for individuals, then simplify the form by un-checking Demographics.
• Advanced Search - Control the sections that should be included in the Advanced Search form. EXAMPLE: If you don't track Relationships - then you do not need this section included. Simplify the form by un-checking this option.
• Contact Dashboard - This dashboard can allow your constituents to view the groups they are subscribed to, their contribution history, event registration information and more. You can control the sections that should be included in the dashboard here. EXAMPLE: If you don't want constituents to view their own contribution history, un-check that option.
• WYSIWYG Editor - Select the HTML WYSIWYG Editor that is provided for fields that allow HTML formatting (such as the introductory section for your online contribution pages). You can choose either FCKEditor or TinyMCE. It's a good idea to try out both and see which is more comfortable for you and your users.

Address Settings

CiviCRM allows you to modify the default fields for adding and editing contact and event address data. You can also change the address field layout used for screen display and mailing labels. Review the out-of-the-box defaults by adding a new contact record and noting the address fields provided on the form. Save the record and note the order in which the fields are displayed on the Contact Summary screen. If you plan on generating mailing labels for contacts - you should also review the label layout (select Mailing Labels from the -more actions- drop-down after doing a search using the Find Contacts menu option).

After reviewing the default fields and layouts - review the Address Settings screen and make changes as needed.

• Mailing Labels - Modify mailing label formatting here. The default format is:
  

  {contact.contact_name}
  {contact.street_address}
  {contact.supplemental_address_1}
  {contact.supplemental_address_2}
  {contact.city}{, }{contact.state_province}{ }{contact.postal_code}{contact.country}

  You must include the special {contact_name} token here in order to include the contact name in your labels. If the label is for an individual, the Individual Name Format is used (see the next bullet item). For organizations - the Organization Name is used. For households, the Household Name is used. Users will be able to select from a variety of label types corresponding to the label manufacturer code when they generate the labels from a list of contacts. It's a good idea to test your format with the type of label and printer you plan on using to verify spacing.
  
• Individual Name Format - Modify the order and the specific fields used for individual contact names when they are included in mailing labels. The default format is:
  

  {individual_prefix}{ }{first_name}{ }{middle_name}{ }{last_name}

• Address Display - Modify the layout for contact and event location addresses when displayed on CiviCRM screens. The default format is:
  

  {contact.address_name}
  {contact.street_address}
  {contact.supplemental_address_1}
  {contact.supplemental_address_2}
  {contact.city}{, }{contact.state_province}{ }{contact.postal_code}{contact.country}
  

  [TIP] This format applies to event locations, despite the use of the contact. record type in the layout. The {contact.address_name} field is particularly useful for events where you need to include a location name (e.g. "Smithson Hall"). [/TIP]
  

• Address Editing Fields - Modify the available address editing fields here. You can hide fields that you don't plan on using in order to simplify the forms. EXAMPLE: If you don't plan on recording OpenIDs for contacts, you can uncheck that field.
  
• Number of Locations - You can control the maximum number of different locations/addresses that can be entered for each contact. The default value is 1 location. If you plan on recording Home and Work addresses for some contacts, for example, then increase this number here.
• Address Standardization - CiviCRM includes an optional feature for interfacing to the United States Postal Services (USPS) Address Standardization web service. You must register to use the USPS service at http://www.usps.com/webtools/address.htm. If you are approved, they will provide you with a User ID and the URL for the service. The URL provided by USPS will not be prefixed with "http://". When entering this URL into the CiviCRM settings field, you must prefix it with "http://".

Mapping and Geocoding

CiviCRM includes support for both the Google and Yahoo mapping services. These services allow your users to display contact addresses and event locations on a map. To enable this feature, select your mapping provider and obtain a 'key' for your site from that provider. Map coverage outside of the United States may vary between providers - so it's a good idea to investigate coverage if you expect to store a significant number of non-US addresses.

Once a mapping provider is enabled, your contact and event records will be automatically geocoded (the latitude and longitude for that address is inserted) as you add or edit address data.

Version Checking, Search Behaviors and CAPTCHA

Use the Miscellaneous Settings screen to configure and control the following behaviors:

• Version Checking and Statistics Reporting - This feature automatically checks availability of a newer stable version of CiviCRM. New version alerts are displayed on the main CiviCRM Administration page. Statistics about your CiviCRM installation are also reported anonymously to the CiviCRM team to assist in prioritizing ongoing development efforts. The following information is gathered: CiviCRM version, versions of PHP, MySQL and framework (Drupal/Joomla/standalone), and default language. Record counts (but no actual data) are also reported. You can set this field to No if you are not comfortable with having this information reported for your site.
• Attachments - You can increase or decrease the maximum number of files (documents, images, etc.) which can attached to emails, activities, and grant records. The default value is 3.
  
• Contact Searches -

[TIP] A wildcard character is a special character that can be used to substitute for any other character or characters in searches. CiviCRM allows you to use the percent - '%' - character to substitute for zero or more characters, and the underscore - '_' - character to substitute for any single character. Wildcards are useful for broadening your search results.

EXAMPLE: Typing 'Volunteer%' as your Activity Subject will match any record whose subject contains 'Volunteer' + any other words (e.g. 'Volunteer for Open House'). [/TIP]

• Automatic Wildcards - By default, wildcards are automatically added when users search for contacts by Name. EXAMPLE: Searching for 'ada' will return any contact whose name includes those letters - e.g. 'Adams, Janet', 'Nadal, Jorge', etc. Disabling this feature will speed up searches significantly for larger databases, but users must use wildcard characters for partial name searches (e.g. '%' or '_').
• Include Email - By default, email addresses are automatically included when users search by Name. Disabling this feature will speed up searches significantly for larger databases, but users will need to use the Email search fields (from Advanced Search, Search Builder, or Profiles) to find contacts by email address.
• Include Nickname - By default, nicknames are automatically NOT included when users search by Name. Change this value to Yes if you want nicknames to be included.
  
• Smart group cache timeout - Smart groups are basically saved searches. The list of contacts for each smart group is cached in the database in order to avoid running the saved search every time you access a smart group. This field determines the number of minutes to maintain this cache before refreshing it. The default value of 0 means the cache is emptied immediately when any contact is edited or a new one is added. If your contact data changes frequently, you may want to try setting this to a value of 5 minutes (or longer) to reduce processing load on your server.
• reCAPTCHA - reCAPTCHA is a free service that helps prevent automated abuse of your site by requiring users to read a random pair of words and type them into the form. To use reCAPTCHA on public-facing CiviCRM forms: sign up at recaptcha.net; enter the provided public and private reCAPTCHA keys here; then enable reCAPTCHA under the Advanced Settings section in any Profile.

[TIP] If you want to use reCAPTCHA protection for online contribution, membership signup or event registration forms - then you'll need to configure a Profile with reCAPTCHA enabled, and then include it in those forms. [/TIP]

Sending Emails

CiviCRM will use the default FROM address defined here when sending automated emails. If you've already entered an email address in the Domain Information screen, that address will be listed here.

Outbound Email

If you are sending emails to contacts using CiviCRM then you need to enter settings which allow CiviCRM to connect to your mail server. This includes sending receipts to contributors, sending confirmations to people registering for events, and using CiviMail to send bulk mailings.

CiviCRM supports two different methods of connecting to a mail server: SMTP (Simple Mail Transport Protocol) OR Sendmail. Each method requires that you enter specific settings. If you're unfamiliar with these terms, or unsure of the correct values for these settings, check with your system administrator, ISP or hosting provider.

You should always send a test email when you enter or modify the settings on this screen. Simply click "Save and Send Test Email". An email will be sent to the email address associated with your user login. The FROM email address will be the default FROM address you've configured in the previous section.

If CiviCRM is unable to send the test email, you will see a message on your screen with the specific error and some suggestions for trouble-shooting the problem.

Note: If you do NOT want users to send outbound emails from CiviCRM at all, select "Disable Outbound Email". However, if you disable outbound email, and you are using Online Contribution pages or online Event Registration - you will need to turn off the automated receipting and registration confirmation features (these are enabled by default). Otherwise your constituents will see error messages after they've completed a contribution or registration.

Payment Processors

Payment processors are companies that handle credit card transactions for merchants and / or non-profit organizations and transfer funds to the organization's bank account. If you plan on using CiviCRM to accept online contributions, online membership signup and renewal or online event registration, then you will need to select and configure a payment processor for your site.

CiviCRM includes support for several different processors, and provides a way for 3rd party developers to add support for additional processors based on their clients' needs. Each processor has their own pricing structure and features, and you will want to investigate each available option to determine the best fit for your organization. Refer to the Fundraising section for a list of factors to consider in selecting a processor.

The actual steps involved in configuring and testing your payment processor connection are different for each processor. For more information, visit:
http://wiki.civicrm.org/confluence/display/CRMDOC/CiviContribute+Payment+Processor+Configuration 

Permissions for anonymous users

Note: This section applies to Drupal sites only.

If you are using CiviCRM with Drupal, you will need to review user permissions to ensure that people can get to your signup forms, contribution pages, membership pages and event registration pages.

You must be an administrator for your Drupal site to review and modify user permissions. Login to your Drupal site, and navigate to Administer » User Management » Permissions.

Then review each of the permissions listed below. You should enable them for the anonymous user role if you want these features to be accessible to people who are visiting your site but are NOT  logged in:

• Make online contributions:
  If you plan to use CiviContribute and want to allow online contributions, enable this permission by checking the box.

• View event info and Register for events:
  If you plan to use CiviEvent and want to allow online event registration, enable BOTH of these permissions.

• Profile listings and forms:
  If you want to either collect contact information from constituents and/or expose a searchable directory using a profile, you must enable this permission.

• Access all custom data:
  You must enable this permission for any role which you want to view or edit custom data fields. This permission sounds like one that should be given out with care but in reality most sites give this permission to anonymous users as it is required for simple tasks like filling in information about themselves in custom data fields which you include in the event registration process. If your site uses Profile(s) which include custom fields, make sure the role(s) that need to access these Profiles have this permission.
  

Now that you have reviewed all the basic configuration tasks, you're ready to begin exploring the ways in which you can record and use contact data.