CONTENTS -------- I. Software requirements II. Apache configuration III. PHP configuration IV. Installation: automated V. Installation: manual VI. CivicSpace Configuration VII. Cron tasks VIII. Adding other Drupal modules I. SOFTWARE REQUIREMENTS ------------------------ CivicSpace requires the Apache HTTP server 1.3 [1], PHP4 [2], and MySQL 4.0.x or 4.1.x [3]. CivicSpace requires PHP 4.3.3 or greater. PHP5 is not yet supported. If you wish to use CivicSpace's image-related features, you will need to install a seperate software package on your hosting machine. For Linux hosts, you can use either the GD library for PHP [4] or ImageMagick [5]. ImageMagick can also be used on a Windows server. NOTE: You will need to use php as an Apache module (mod_php), as opposed to running PHP under CGI, if you want to run the automated installer. If you have no choice but to run CivicSpace under CGI, you will have to follow the manual installation instructions (which require command-line access for the server and mysql database). [1] http://httpd.apache.org [2] http://www.php.net/ [3] http://www.mysql.com [4] http://www.php.net/gd [5] http://www.imagemagick.org/ II. APACHE CONFIGURATION ------------------------ If you wish to enable clean URLs, your Apache must be configured to allow ".htaccess" files to override all the main server settings. For details on how to do this, please consult the Apache documentation at http://httpd.apache.org/docs/mod/core.html#allowoverride If you are setting up a site on a virtual hosting service, your service provider will know how to properly do this. III. PHP CONFIGURATION ---------------------- The values for PHP settings are normally set by the ".htaccess" file. If for some reason this file is not being recognised by Apache, the settings may be configured in the server's "php.ini" file. You can print out your local PHP settings with PHP's "phpinfo()" function. Settings which are configured by default by ".htaccess" include: register_globals 0 track_vars 1 short_open_tag 1 magic_quotes_gpc 0 magic_quotes_runtime 0 magic_quotes_sybase 0 arg_separator.output "&" session.cache_expire 200000 session.gc_maxlifetime 200000 session.cookie_lifetime 2000000 session.auto_start 0 session.save_handler user session.cache_limiter none allow_call_time_pass_reference On These recomended settings should not be changed. Additionally, you may need to increase PHP's memory limit by editing the "php.ini" file. If you are using a shared hosting service you may have to ask to have this changed. memory_limit 24M This much memory is the worst case. The average memory usage is significantly less. IV. AUTOMATED INSTALLATION -------------------------- 1. DOWNLOAD CIVICSPACE You can obtain the latest CivicSpace release from http://civicspacelabs.org/download/ Download the current tgz format and extract the files: $ tar -zxvpf civicspace-x.x.x.tgz This will create a new directory civicspace-x.x.x/ containing all CivicSpace files and directories. Move the contents of that directory into a directory within your web server's document root or your public HTML directory: $ mv civicspace-x.x.x/* civicspace-x.x.x/.htaccess /var/www/html 2. INSTALL CIVICSPACE Once your files have been copied to the document root or desired path under the document root, you can install CivicSpace by browsing to: http://www.example.com/install.php If you're installation is not in your web server's root directory but in some subdirectory, for example "path/subpath", then you should instead browse to: http://www.example.com/path/subpath/install.php *** Please Note *** The URL with which you access the installer (install.php) will be used to create all of the links within your CivicSpace site. If you are installing CivicSpace on a private network or localhost and wish to access your CivicSpace site from outside of the private network, you must browse to a URL that includes the public domain name. For example, you should use http://www.example.com/install.php instead of http://localhost/install.php, http://127.0.0.1/install.php, or http://192.168.x.x/install.php. The installer will walk you through the server-level configuration and populating your initial database tables. 3. CONFIGURE CIVICSPACE The last page of the installer will present you with a button labelled "configure your site." Click on it to proceed to the configuration wizard of your new site. Proceed to Step VI. V. MANUAL INSTALLATION ---------------------- 1. DOWNLOAD CIVICSPACE You can obtain the latest CivicSpace release from http://civicspacelabs.org/download/ Download the current tgz format and extract the files: $ tar -zxvpf civicspace-x.x.x.tgz This will create a new directory civicspace-x.x.x/ containing all CivicSpace files and directories. Move the contents of that directory into a directory in your web server's document root or your public HTML directory: $ mv civicspace-x.x.x/* civicspace-x.x.x/.htaccess /var/www/html 2. CREATE THE CIVICSPACE DATABASE This step is only necessary if you don't already have a database set-up (e.g. by your hosting provider). If you control your databases through a web-based control panel (such as phpMyAdmin), check its documentation for creating databases, as the following instructions are for the command-line. In the following examples, "dba_user" is an example MySQL user which has the CREATE and GRANT privileges. You will need to use the appropriate user name for your system. First, you must create a new database for your CivicSpace site: $ mysqladmin -u dba_user -p create civicspace MySQL will prompt for the dba_user database password and then create the initial database files. Next you must login and set the access database rights: $ mysql -u dba_user -p Again, you will be asked for the dba_user database password. At the MySQL prompt, enter following command: GRANT ALL PRIVILEGES ON civicspace.* TO 'nobody'@'localhost' IDENTIFIED BY 'password'; where 'civicspace' is the name of your database 'nobody'@'localhost' is the userid of your webserver MySQL account 'password' is the password required to log in as the MySQL user If successful, MySQL will reply with Query OK, 0 rows affected to activate the new permissions you must enter the command flush privileges; and then enter '\q' to exit MySQL. 3A. LOAD THE CIVICSPACE DATABASE SCHEME If you use a web-based control panel (e.g., phpMyAdmin), you should be able to upload the file 'civicspace.mysql' from CivicSpace's 'database' directory and run it directly as SQL commands. Once you have a database, you must load the required tables: $ mysql -u nobody -p civicspace < database/civicspace.mysql $ mysql -u nobody -p civicspace < database/zipcodes.mysql 3B. LOAD THE CIVICRM DATABASE SCHEME To install the CiviCRM database tables, you need to determine the MySQL version you are using. To this end, login to the mysql prompt of your database (either as root or with the login/passwd you just created) and then get the version by typing the following at the mysql prompt: mysql> select version(); You will get a response that tells you what version of MySQL your server is running: +-----------+ | version() | +-----------+ | 4.0.20 | +-----------+ If your MySQL version starts with "4.0", you will need to load the MySQL-4.0 version of the CiviCRM database schema, after you exit the mysql prompt: $ mysql -u nobody -p civicspace < database/civicrm_40.mysql If your MySQL version starts with "4.1", you will need to load the MySQL-4.1 version of the CiviCRM database schema, after exiting back to the regular prompt: $ mysql -u nobody -p civicspace < database/civicrm_41.mysql Finally, you will want to load some basic data into the CiviCRM tables: $ mysql -u nobody -p civicspace < database/civicrm_data.mysql 4A. CONNECTING CIVICSPACE CivicSpace server options are specified in sites/default/settings.php Before you can run CivicSpace, you must set the database URL and the base URL to the web site. Open the sites/default/settings.php file and edit the $db_url line to match the database defined in the previous steps: $db_url = "mysql://username:password@localhost/civicspace"; Set $base_url to match the address to your web site: $base_url = "http://www.example.com"; NOTE: for more information about multiple virtual hosts or the configuration settings, consult the Drupal handbook at drupal.org: http://drupal.org/node/274 4B. CONNECTING CIVICRM CiviCRM server options are specified in sites/default/civicrm.php Before you can run CiviCRM (or CivicSpace, for that matter), you will need to set several values in civicrm.php file. Open the sites/default/civicrm.php file and (i) Edit the line that starts with "$civicrm_root = ", so that it reads $civicrm_root = './modules/civicrm'; (ii) Edit the next line, the one that starts with "define('CIVICRM_TEMPLATE_COMPILEDIR'", so that it reads define( 'CIVICRM_TEMPLATE_COMPILEDIR', './files/civicrm/templates_c/'); (iii) Edit the next line, the one that starts with "define('CIVICRM_UPLOADDIR'", so that it reads define( 'CIVICRM_UPLOADDIR', './files/civicrm/upload/'); (iv) Next, find the line that starts with "define( 'CIVICRM_HTTPBASE'" and edit it so that it reads define( 'CIVICRM_HTTPBASE', '/base/path/'); HOWEVER, you will want to replace "/base/path/" with the actual path from your $base_url (as set in settings.php; see above). For example, if you intend to install your site so that it is the home page is under a subdirectory or some other location other than the regular document root, say http://www.example.com/~ankur then you will want to change the line so that it reads define( 'CIVICRM_HTTPBASE', '/~ankur/'); NOTE: Make sure you inlcude the preceding and trailing slashes for this particular value. (v) Now, edit the next line, the one that starts with "define( 'CIVICRM_RESOURCEBASE'", so that it reads define( 'CIVICRM_RESOURCEBASE', '/base/path/modules/civicrm/'); HOWEVER, REMEMBER to replace '/base/path/' with the path appropriate for your setup, keeping the 'modules/civicrm/' portion of the line on the end of the value that you enter. (vi) Next, edit the next line, which starts with, "define( 'CIVICRM_MAINMENU'" so that it reads, define('CIVICRM_MAINMENU', '/base/path/civicrm/'); AGAIN, REMEMBER to replace '/base/path/' with the path required by your installation, making sure to keep 'civicrm/' on the end of it. (vii) Now, find the line that starts with "define('CIVICRM_MYSQL_VERSION'" and edit it so that it reads define('CIVICRM_MYSQL_VERSION', 4.0); if you are using a version of MySQL that is 4.0.x. However, if you are using a version of MySQL that is 4.1.x, you will want the line to read define('CIVICRM_MYSQL_VERSION', 4.1); (viii) Finally, edit the next line that starts with "define('CIVICRM_DSN'" and edit it so that it reads define( 'CIVICRM_DSN', 'mysql://user:pass@localhost/database?new_link=true'); HOWEVER, you will want to replace the portion 'mysql://user:pass@localhost/database', with a the database URL that you entered for the $db_url value in settings.php (see above). MAKE SURE you retain the '?new_link=true' on the end of the URL however. The CiviCRM instruction here describe what needs to be done for the most basic setup (i.e., one CivicSpace site with one CiviCRM, not a multisite/multi-CiviCRM or multisite/single-CiviCRM setup). To get more info on how to manually set up multiple installations of CiviCRM, you should consult the CiviCRM installation documentation available at: http://objectledge.org/confluence/display/CRM/Installation+Guide 5. CONFIGURE CIVICSPACE The last page of the installer will present you with a button labelled "configure your site." Click on it to proceed to the configuration wizard of your new site. Proceed to Step VI. VI. CIVICSPACE CONFIGURATION ---------------------------- Once you've installed CivicSpace, browse to the main page of your site: http://www.example.com/ or, if you have installed CivicSpace in a directory called "path/subpath", http://www.example.com/path/subpath/ Be sure to include the trailing slash in the the URL that you use. The first page you will encounter when you go to your new site is the configuration wizard, which will walk you through a number of site-specific settings. You will be able to fine-tune the configuration later through your site's configuration interface. (See VII. CRON TASKS, below) VII. CRON TASKS --------------- Many CivicSpace modules have periodic tasks that must be triggered by a cron job. To activate these tasks, you must call the cron page; this will pass control to the modules and the modules will decide if and what they must do. The following example crontab line will activate the cron script on the hour: 0 * * * * wget -O - -q http://HOSTNAME/cron.php More information about the cron scripts are available in the admin help pages and in the Drupal handbook at drupal.org. Example scripts can be found in the scripts/ directory. For more information, please consult http://drupal.org/node/288 VIII. ADDING OTHER MODULES -------------------------- CivicSpace 0.8.2.x is based on Drupal 4.6. You should be able to add any Drupal 4.6-compatible modules to an installation with few problems. For details on how to add contributed Drupal modules not already in the CivicSpace distribution, please consult the documentation available at http://drupal.org/node/17473