Installing the Facebook Open Platform

Facebook is cool. It's a little past its best now (it may be seen as 2007's YoYo) but the technology underneath it is proven, scalable and solves many of the problems any site wanting to introduce some 'magic social dust' contains.

Now, Facebook have released their Facebook Open Platform. This looks interesting. Not sure what I can do with it yet, but its a nice thing to start messing around with - particularly the FBML and FBJS implementations - FBML especially as it's a lovely thing which we can use for all kinds of simple site layout things.

It wasn't totally easy getting it up and running, but here's my method which you're welcome to follow if you'd like.

Background

I'm running Apache on CentOS with PHP 5.1.6 already installed and working with Apache. In this tutorial, I'll assume you have:

• Apache 2+
• PHP 5+ working with Apache
  
• CentOS
• FTP/sFTP access to your server
• command line access with sudo permissions where needed (for restarting Apache and editing httpd.conf for example)
• MySQL 5+ working with PHP
  

Getting Started

1. Grab the code from Facebook: http://developer.facebook.com/fbopen/
2. Unzip
3. FTP to your server and create a folder in your webroot like 'fbop'. This will be where your instace of the platform lives i.e http://www.example.com/fbop/
4. Upload the contents of the 'html' folder in the unzipped fb-open-platform folder into your new 'fbop' folder on your web server. If you now go to http://www.example.com/fbop/fbopentest/fbml.php you'll see a ton of errors. That's okay, we'll fix them in a bit.
5. Now, choose where you want your facebook open platform libraries to live. Sensibly, this will be away from your webroot, but with all your other php libraries. I've chosen /var/www/fblib/lib. Go ahead and create this folder and upload the contents 'lib' folder from your unzipped fb-open-platform folder.

You should now have the following files uploaded to your webserver in roughly the following ways.

• /var/www/fblib/lib/
• api/
• common.php
• core/
• display/
• .....
• /var/www/html/fbop/
• api/
• canvas.php
• common/
• fbml/
• fbopentest/
• js/
  

So far so good. But we still have all those errors at http://www.example.com/fbop/fbopentest/fbml.php

Configuring Apache

Facebook have been a bit wierd and rather than telling PHP where to look for includes like most apps, they've set a custom Apache variable which PHP then uses to find some files. This isn't easy info to find out by Googling, but its very simple to implement.

1. Open your httpd.conf file.
   
2. At the bottom, or near your other non-standard config changes, add the line...
   SetEnv PHP_ROOT "/var/www/fblib"
3. This sets a new variable constant in Apache called 'PHP_ROOT'. From within PHP this is now accessible using the $_SERVER["PHP_ROOT"] variable. The lack of this variable being present was that cause of all those errors we've been seeing.
4. Restart Apache. For me on CentOS, this means running $sudo /sbin/service httpd restart
5. You should now be able to test if this has worked by creating a new PHP file, and adding (inside you php braces, this line... print_r($_SERVER); . Opening that in a browser will list all the server variables available to PHP. Magically, one of them should be PHP_ROOT with the value you specified earlier. This is good.
   

Now, going to http://www.example.com/fbop/fbopentest/fbml.php will give us no errors! Sadly it won't do much else.

Configuring the database

Just like Facebook itself, running apps on the Platform requires the Platform to keep a list of all the applications running on it. In the Open Platform, this is held in a MySQL database. Helpfully, they provide you with enough data to get you started, you just have to load it into MySQL.

1. Connect to MySQL using your favourite client - I'll use phpMyAdmin
2. Create a user which which we'll give to the Platform so it can access the database
3. In the SQL Tab, copy and paste the contents of the file /fbopen_data_dump where fb-open-platform is the archive you downloaded and unzipped from Facebook
4. Run the Query

You should see a database called 'fbopentest' has been created with 12 tables. If you can't see this, the query may have errored. Have a look at your debug and see why. In my case, phpMyAdmin threw an error at the comments which had three dashes preceeding them '---' instead of the usual two '--'. Odd, but thats textual SQL for you. It never works first time. Changing those in the three lines in which it appeared got me up and running.

Now we have to configure the Platform to talk to the database.

• On your web server, edit a file in the fb open platform lib directory - in our example, I mean this file: /var/www/fblib/lib/core/init.php
• Change $DB_USERNAME to match the user you created. In my case it was 'fbopenplatform'
• Change $DB_IP to match IP address of your database server. In most cases, this will just be 'localhost'
• Change $DB_PASSWORD to match the user's password you created earlier. I'm not going to tell you what mine was ;-)
• Save the file.

To test if this has been successful,

Hold up. You with me?

Before we go any further, lets test that the basics of the facebook open platform are up and running. In a browser, go to your http://www.example.com/fbop/fbopentest/ folder. You should see a nice list of test file we can use. At present, the most interesting one is http://www.example.com/fbop/fbopentest/fbml.php. You'll see that it loads, and you can see all the code if you view source, but its not parsing it into HTML from FBML. That's because we haven't installed the FBML parsing libraries yet!

This is a little more tricky for the novice as we're not messing about with PHP anymore - but proper unix and C++ stuff, but lets have a go. I would however, ensure you have a backup of your server or virtual machine. If this screws up, it has the capacity to ruin your install of a number of other things as Sean B discovered.

Installing the FBML Parser

Back soon to finish this off.