Requirements and Assumptions
This tutorial will be updated regularly as the versions of WPMu, BuddyPress, and bbPress are updated and stabilized. Currently, this tutorial assumes you have WPMu 2.7.1 installed (which can be found here), the BuddyPress Combo 1.0.2, and bbPress 1.0 RC 3. Also, I am running this setup on a LAMP server with PHP and MySQL 5+.
Installing WPMu is its own ball of wax, and it can be tricky if you decide to do dynamic domains as opposed to sub-directories (though I recommend sub-domains given the power of the Domain Mapping and the Sitewide Tags Pages plugins).
Nonetheless, Andrea_R has an excellent e-book tutorial for installing WPMu which you can download from the WPMU Tutorials site here. I'd start there, and then go to the WPMu forums as needed, where Andrea_R will answer all your questions :)
From here on out I will assume you have WPMu up and running without a hitch for the rest of this tutorial.
Installing BuddyPress is extremely straightforward once you have WPMu up and running. In fact, the beauty of BuddyPress is that it is a series of plugins, which means all you have to do is copy a series of files into the plugins folder in your WPMu installation. The only exceptions are the theme files and a bbPress plugin for the Group Forums which I will discuss further along.
Paraphrased From the BuddyPress installation documentation:
Move the themes to the correct locations. In the folder “plugins/buddypress” you will find "bp-themes” which has the the bphome, bpmember, bpskeletonmember directories. Move the entire “bp-themes” directory intto “wp-content.” If you want to use the default BuddyPress theme for your main site move the bphome directory into wp-content/themes and activate that them on your main blog.
You should now have the following folder locations “/wp-content/plugins/buddypress/” and “/wp-content/bp-themes/” (and wp-content/themes/bphome is you chose that option)
That's it on the server side for BuddyPress, see the rest of the details for setup here.
When installing bbPress and opting for integration, you may come across a few questions. I tried to integrate right off the bat during the intallation, but hit a few snags with authentication keys and salts. I highly recommend Sam Bauers's screencast tutorial of the process of integrating WP and bbpress here. Also, you can find the official documentation on the bbPress site here.
From what I've seen in the forums, you might want to consider putting the forums within your WPMu installation directory, it makes integration with WPMu easier, for example: public_html/my_wpmu_install/bbPress_forums/
In the event the integration of WPMu and bbPress didn't go smooth during the install, don't worry too much about it---just go on to the next section of this tutorial.
Integrating bbPress with WPMu
When we talk about integrating bbPress and WPMu, we are basically saying the following two things:
- The two applications share a common database of users (the wp_users table in WPMu)
- The two applications share cookies so that a user logged into the WPMu install is automatically logged into the bbPress forums (and if they log out of one they are automatically logged out of the other).
I got all of the information on how to do this from the bbPress support forums (with a special thanks to Sam Bauers). I'm just going to include the stuff I found useful for me during the integration, providing links out to the actual forum topics and other resources.
Also, for a far better tutorial, see the screencast Sam Bauers created that will take you through the basics of integration. It's excellent, and you can find it here.
One last remark: if you are using LDAP for your WPMu installation, you may want to check out Joss Winn's comment here.
You will need to install and activate the following plugins in your WPMu installation:
- bbPress Integration: This is essential, but keep in mind that this plugin is only useful if you are running bbPress version 1.0-rc3 or later.
- WPMU Enable bbPress Capabilities (0.1): (Please note that Mark Ghosh found a HUGE bug in this plugin and offers a fix here.) Enables bbPress member capabilities when a user is created within WPMU. This allows immediate login as a 'member' after a user is created in WPMU.
Resetting the secure keys in wp-config.php
One of the problems I had with integration was with the Authentication Unique keys in the wp-config.php and the bb-config.php files.
Warning: the recommendation below to delete the unique authentication keys may be terrible advice for existing sites for reasons I admittedly do not know, if this is the case please let me know.
What I would recommend if you have a pre-existing WPMu account, is that you delete all the Unique Authentication Key values from your wp-config.php files, and let WPMu generate new ones, which will show up in the admin Dashboard, something like this:
convert: missing an image filename `/home/umwblogs/public_html/wiki/images/thumb/Unique_authentication_key.jpg/480px-Unique_authentication_key.jpg' @ convert.c/ConvertImageCommand/2800.
Also, don't be too concerned if you didn't get all the keys listed below (you probably won't see a couple of the salt values), just see the next section on the "bbPress Backend Integation Tab" to locate the rest of them.
define( 'AUTH_KEY', 'unique-authentication key here' ); define( 'LOGGED_IN_KEY', 'unique-authentication key here' ); define( 'SECURE_AUTH_SALT', 'unique-authentication key here' ); define( 'NONCE_KEY', 'unique-authentication key here' ); define( 'AUTH_SALT', 'unique-authentication key here' ); define( 'LOGGED_IN_SALT', 'unique-authentication key here' ); define( 'SECURE_AUTH_KEY', 'unique-authentication key here' ); /**#@-*/
Once you have all the values above defined in your wp-config.php file, put those very same values for each line in the corresponding space in your bb-config.php file:
define( 'BB_AUTH_KEY', 'unique-authentication key here' ); define( 'BB_LOGGED_IN_KEY', 'unique-authentication key here' ); define( 'BB_SECURE_AUTH_SALT', 'unique-authentication key here' ); define( 'BB_NONCE_KEY', 'unique-authentication key here' ); define( 'BB_AUTH_SALT', 'unique-authentication key here' ); define( 'BB_LOGGED_IN_SALT', 'unique-authentication key here' ); define( 'BB_SECURE_AUTH_KEY', 'unique-authentication key here' ); /**#@-*/
bbPress Backend Integration Tab
Once you have entered the unique authentication keys, login to the bbPress forums and find the Settings --> WordPress Integration subtab. Here you will need to enter a few values and adjust a couple of settings
First off, in the User Role Map section choose the role you want to map for particular levels of users. The rule of thumb I followed with WPMu is to make everyone a member at first (including administrators), and you (the uber-admin of the WPMu account) will be the keymaster of bbPress, and you can promote others as need be. (Once again, let me know if this misguided advice.)
After this, you will see the User Integration section.
convert: missing an image filename `/home/umwblogs/public_html/wiki/images/thumb/BbPress_cookies.jpg/480px-BbPress_cookies.jpg' @ convert.c/ConvertImageCommand/2800.
If you don't have all the values needed here already in the config files, each of the fields has some text and links that will take you to the actual values in the WordPress Options.php section of the main blog of your WPMu install. Check there to see if any missing keys or salts can be found.
bbPress Integration Plugin
You should now download, install (in wp-content/plugins), and activate the bbPress integration plugin at this point.
When you activate it in your WPMu main blog and go to Settings--bbPress integration, you'll be asked to add the URL to your forums as well as the URL to your my-plugins folder (which is you haven't created in bbPress you should in the root of the bbPress directory).
After you add your URL you'll see something like this to be added to your wp-config file:
define( 'COOKIEHASH', '####################' ); define( 'COOKIE_DOMAIN', '.yourdomain.org' ); define( 'SITECOOKIEPATH', '/' ); define( 'COOKIEPATH', '/' );
And another line to be added to your bb-config file (this is only for versions of bbPress running on WP/WPMu install that are versions prior to WP 2.8.
define( 'WP_AUTH_COOKIE_VERSION', 1 );
Now, that setup didn;t work for me entirely, I had to change the COOKIE_DOMAIN in my wp-config file, and include the new COOKIE_DOMAIN, SITECOOKIEPATH and COOKIEPATH in my bb-config file. So, my wp-config looks like this (please remember this is for WPMu 2.7.1--your own mileage may vary with WP 2.8):
define( 'COOKIE_DOMAIN', '' ); define( 'SITECOOKIEPATH', '/' ); define( 'COOKIEPATH', '/' ); define( 'COOKIEHASH', '###################' );
And my bb-config looks like this:
define( 'WP_AUTH_COOKIE_VERSION', 1 ); define( 'COOKIE_DOMAIN', '' ); define( 'SITECOOKIEPATH', '/' ); define( 'COOKIEPATH', '/' );
I really think the bbPress 1.0-RC3 has made finding this a lot easier with the bbPress Integration plugin. Moreover, they give you the line of code you need. The Cookie Hash they had pre-populated for me there worked beautifully. But if it doesn't, take a look at some of the ideas for finding it on your own below.
If you need to locate your Cookie Hash and you are using Firefox, that means going to the privacy tab in preferences and clicking on show cookies, then look for the domain you are integrating on. You should find something like this:
So, the line should be
Here's an additional trick, if for some reason the Cookie value in the browser doesn't work. I found that you can take the cookies that show up in the Manual bbPress Config within the Settings-->WordPress Integration tab, specifically the value in the $bb->authcookie = (without the wordpress_) and give it a try. It might work, it did for me.
Integrating BuddyPress Group forums with bbPress
I'm reproducing it verbatim below, because I couldn't even begin to detail it any clearer or better:
bbPress Side (First):
1) you have bbpress installed and a new user created on the "bbPress" side which you granted "administrator" rights by the keymaster
2) you copy the "buddypress-enable.php" plugin out of the bp-forums folders and copy it into your /my-plugins/ folder (create if it doesn't exist) so it is /my-plugins/buddypress-enable.php
3) Enable the plugin through your bbPress administration side for plugins
4) Edit "settings" to enable xmlrpc and pingbacks (both)
5) edit your bb-config.php and just before the closing php call at the bottom of the page put:
$bb->bb_xmlrpc_allow_user_switching = true;
buddypress Side (Second):
6) Go into your main blog dashboard and go to the BuddyPress Forums admin page sections of the sidebar. Put in the URL of your forum like http://yoursite.com/forums/ and make sure you have the ending slash on that one.
7) Put in the user that you created in step 1 with the bbPress "administration" rights and their password. I never changed the password, just used the random one it sent me, but it is up to you. I usually save it a couple of times to ensure it was entered due to a refreshing bug at time of writing this. (Actually, I think if the integration worked you can just put your WPMu login and password, no need to be confused here by a separate bbPress login.)
8) Go to one of your groups (new or existing) and go to the group admin page. Make sure "discussion" is turned off. If it was already off that is fine, but if it was enabled already, turn it off
9) Turn the group "discussion" back on and then physically go to your forums URL and see if it created the forum on the bbPress side without trying to create a new topic on the buddypress side.
If you have the new forum now, then you should skip to step 10. If not, go through steps 1-9 again and make sure you got all the steps perfectly.
10) If you have made it this far, it will work, but I like to create the first post in the new forum on the bbPress side and then see if it shows up in the buddypress group forum. Old habit, but for odd circumstance, it seems to work best for me. If it works, try creating a new topic on the group you have working.
- Don't forget that you have to do step 8 for every group that was created before you enabled the forum integration! Very important***
1) The refreshing bug in step 7 killed it for me a couple of times and I made sure I saved it at least 2 times.
2) Forgetting the line in bb-config.php killed it for me a couple of times as well.
3) In one install I had to change the bbPress "user" with administration rights password and on the bbPress side and then completing step 7 again.
4) I also found that through "previous testing" I had some bp_groupmeta entries that were screwing things up with duplicates for the same forum in the database. Shouldn't happen to anyone else, but that screwed some things up for me as well.
In terms of having buddypress and bbPress working together, I am sure it works with buddypress on one server and bbPress on another since it works through the xmlrpc module which makes it very powerful.