An outline of the project itself can be found here: ​http://bit.ly/rht93U

Integrating Drupal with BOINC

1. Download Drupal 6 and install it into a prepared web root / virtual host. Alternatively, use a package manager for easier installation. In either case, be sure to include the allow overrides directive, as .htaccess files must be able to work. Also, enable mod_rewrite in Apache, if not so already, so that clean URLs can be used.

2. Clone the BOINC source repository somewhere on the server (e.g. /BOINC/drupal-boinc) and link the sites/all/ directory in the Drupal web root to the drupal/sites/all/ directory in the BOINC source via symbolic link. Also clone the project specific source repository similarly (e.g. /BOINC/drupal) and link the sites/default/project/ directory there to sites/default/project/ in the project specific source.

3. Import a working copy of the BOINC database to MySQL, granting permissions for SELECT, INSERT, UPDATE, and DELETE to an appropriate user (e.g. boinc) on boinc_db_name@localhost. Alternatively, hook into a "live" database for testing on an existing dev platform.

4. Import the pre-configured Drupal database and grant permissions for SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, INDEX, ALTER, CREATE_TMP_TABLE, and LOCK_TABLES to an appropriate user (e.g. drupal_boinc) on drupal_db_name@localhost.

5. Edit the dbconfig.php file in sites/default/ of the web root so that db variables are appropriate for the Drupal database and boinc_db variables likewise allow access to the BOINC database.

Basic functionality should now be in place. Create an account and then set its uid to 1 in the Drupal users table for unlimited admin access in Drupal.

Configure System Features

The Drupal integration system contains a number of Features, which are custom meta packages that provide some specific type of functionality. These might be as simple as providing text for a single link or menu, or as complex as pulling together community contributed modules, custom code, site configurations, and content in order to significantly enhance the site wide experience.

The purpose of Features is to allow for simple deployment of modules and configurations. Rather than install each Drupal module by hand and "replay" any configurations that are required, enabling a Feature automatically satisfies all dependencies required for its logical function and sets default configurations as appropriate. Deployment of Features is best handled on the command line by using drush.

Drush Setup

Drush is a Drupal shell program that provides a command line interface to Drupal and is thus scriptable. While some Linux distributions may have a drush package in their repositories, it is best to get the current package via pear (if php-pear is not installed, install it using the appropriate methods for the distribution):

# pear channel-discover pear.drush.org
# pear install drush/drush

Note: If channel-discover fails, try running "pear upgrade" first.

Another note: The drush command must be used from within a drupal installation, so cd to the drupal site directory to use it.

One more note: The memory_limit setting for the PHP command line interface may need to be increased beyond the default for drush to function! (128M recommended)

Configure BOINC Environment

Some basic environment configuration is required before enabling any features. To access the environment configuration interface, enable the boincuser module:

$ drush en boincuser

Once complete, visit the admin page a web browser: [drupal site url]/admin/boinc/environment

Enter the system path of the BOINC installation for BOINC project root directory and click the [Save configuration] button. In most cases, all necessary paths will be detected from that root directory. If not, overrides can be specified. These configurations can also be set via drush with the following commands, but it is recommended that the web admin interface be used for simplicity:

$ drush vset boinc_root_dir /path/to/boinc
$ drush vset boinc_config_xml_dir /path/to/config/xml
$ drush vset boinc_html_inc_dir /path/to/html/inc
$ drush vset boinc_project_config_dir /path/to/html/project
$ drush vset boinc_user_image_dir /path/to/profile/images

Enable BOINC Features

The Features module must be enabled, if it isn't already, or corresponding drush extensions will not be available:

$ drush en features

Once drush is set up, BOINC features can be enabled via the command line. There are two methods by which to organize the filesystem in this regard, however:

Symbolic links can be created in sites/all/modules/features-enabled pointing back to the desired feature module under sites/all/features. This method is clean and simple and any changes pulled from the source code repository will be instantly available (features will have the status of "overridden" and need to be "reverted" for changes from the source to be made live).

An alternate method of organizing features code is to copy the files for each feature rather than use symbolic links. This can be more difficult to maintain, as the code in sites/all/modules/features-enabled may not match what is in sites/all/features, but it has the benefit of protecting features from being changed inadvertently by a source repository pull. If, for instance, the local version of a feature is in "overridden" status already due to local changes in configuration (within the database), this explicit separation of the live feature code base from the code repository allows the opportunity to update the feature code from the database and then compare any such local changes to changes pulled from the repository for merging. Using symbolic links in this case would have made it impossible to distinguish which changes came from the repository and which were local.

Once one of the prior methods for features code organization has been implemented, the following drush commands can be used to list available features and enable them:

$ drush fl
$ drush en <feature> [<feature>...]

This process will automatically determine which additional features or modules are required and prompt for installation thereof. In some cases, it may be necessary to then force an update from file for all features to revert any "overrides" that exist (i.e. if any functionality provided by a feature already existed in the site database, it will need to be "reverted" to what is provided by the feature on the filesystem):

$ drush fr-all

This command will ensure that all changes in code are applied to the site database. Similarly, when feature code is changed in git, a specific feature or set of features can be updated with the drush fr <feature> command.

We recommend you also enable the diff module as it enables you to display local feature overrides:

$ drush en diff
$ drush fd <feature>

Manual Changes Required

URL Aliases

Required URL aliases include (via web admin at: admin/build/path):

• account -> dashboard
• account/dashboard -> dashboard
• account/info/edit -> user/me/edit
• account/info/edit/profile -> user/me/edit/profile

Menu Configuration

Ensure that the Account menu is present and correct (edit Primary links via web admin at: admin/build/menu). It should contain the following menu items:

• Dashboard
• Profile
• Account Info
• Preferences

If "Dashboard" does not exist, it should be created with the same path as the parent (account/dashboard).

Disable "My bookmarks," which is created by the Flag module, but is not used.

Default Profile Images

Set up a default image for user avatars. Go to: admin/content/node-type/profile/fields/field_image and select a file under the "Default image" section.

Importing BOINC data

With a functional Drupal system hooked into a BOINC database, the best practice is to then import user accounts, teams, and forums into Drupal via the BOINC data import function under the BOINC configuration section in administration. Importing users will generally include avatars, community preferences, private messages, friends, and any "ignored user" flags. At a minimum, all users who participated in the social aspects of the standard BOINC system will be imported. Users who did not have any interactions with other users can instead be imported on-the-fly when they first log into the Drupal system.

Prior to beginning the data import, the process must be configured. Begin with step 1 by reading and making any necessary changes to the settings on the BOINC data import settings page and then click the Save button. If all required settings pass validation, a link will appear to execute the process.

Follow the instructions on screen to work through each stage of the import process.

Notes:

• Input format should be set to Rich text format for imported messages
• Leave BBcode as is to keep existing functionality from BOINC

Post-migration configuration

Additional settings should be explored or verified following the data import.

User settings:

• Visitors can create accounts without admin approval
• Require email verification for new accounts
• Enable signature support

Forum settings:

• How many topics to display per page
• Default order of topics

Further forum settings are available in administration under Content management -> Content types by editing the forum content type and customizing Comment settings:

• Display a flat list of posts or threaded / nested comments
• Order posts ascending or descending by date
• How many posts to display per page
• Allow or disabled the subject field for posts
• Make post preview optional
• Display the comment form below posts rather than on a separate page

The forum itself can also be renamed under Content management -> Taxonomy by clicking the edit vocabulary link for Forum.

Additional Information

• Integrate Apache Solr search: SolrIntegration

Troubleshooting

Errors Referencing Old URLs or File Paths

If there are Drupal caches causing references to files that don't exist, the first thing to try is to access the page at:

/admin/settings/performance

At the bottom is a button to "Clear cached data", which is typically the first thing to try in general Drupal troubleshooting.

If the error prevents even access to that page, create a clear_cache.php file in the Drupal root directory:

<?php
  include_once('./includes/bootstrap.inc');
  drupal_bootstrap(DRUPAL_BOOTSTRAP_FULL);
  drupal_flush_all_caches();
?>

Accessing that page should also clear the cache.

If neither of those work (or if direct DB access is not difficult), go straight to the database and run the following query:

DELETE FROM cache;

There are a number of cache_* tables to clear, but with any luck that one will suffice to then use one of the easier methods above to finish clearing them automatically.

DomDocument Error Preferences Pages

The version of PHP compiled on some systems (RHEL, CentOS) is known to have DOM support disabled by default. If PHP logs appear stating "Class 'DomDocument' not found," look for a php-xml package to install from the distribution repository.