Install Birdcage

Building with the Twitter API

BirdCage Installation Guide

Birdcage is a free, open source PHP-based implementation of the Twitter API, covered in my three part tutorial series for Tuts+: Building with the Twitter API. More features are available in the premium version, Birdhouse.

This guide walks you through installing Birdcage in an Ubuntu 14.04 instance at cloud hosting provider Digital Ocean; it should work similarly for you in other LAMP environments. You can run Birdcage in a localhost development environment but the real time Twitter Stream connection will not function unless you have a consistent DNS connection to your local IP address.

Getting Started

This tutorial describes how to install Birdcage on Ubuntu 14.04 LTS at Digital Ocean for only $5 monthly. You’ll want to have a domain name or sub-domains registered for the app, e.g. http://birdcage.yourdomain.com. If you don’t have a registrar or need more information, I recommend NameCheap.

Creating Your Server Instance

Sign up at Digital Ocean now, the process is simple and only requires your email and password:

signup-do

Digital Ocean’s cloud instances are called Droplets. Once you sign up, you can create your first Droplet using the selections below. You’ll want to have a hostname (domain or sub-domain name) chosen for your readers in mind. You can also select any region closest to you or your typical reader e.g. San Francisco or New York. Under Select Image, choose Applications: LAMP on Ubuntu 14.04 LTS.

[galleria transition=”fade” height=”450″ width=”600″ speed=”1000″ enable=”show_imagenav,pause_on_interaction”][image]http://publishingwithwordpress.com/wp-content/uploads/2014/06/01-digitalocean-menu-1024×576.png[/image][image]http://publishingwithwordpress.com/wp-content/uploads/2014/06/create-droplet-1024×767.png[/image]
[image]http://publishingwithwordpress.com/wp-content/uploads/2014/06/create-droplet-region-1024×773.png[/image]
[image]http://publishingwithwordpress.com/wp-content/uploads/2014/06/create-droplet-distro-1024×799.png[/image]
[image]http://publishingwithwordpress.com/wp-content/uploads/2014/06/03-droplet-creation-status-1024×597.png[/image]
[image]http://publishingwithwordpress.com/wp-content/uploads/2014/06/05-yoursite-com-1024×769.png[/image]
[image]http://publishingwithwordpress.com/wp-content/uploads/2014/06/04-droplet-email-1024×373.png[/image]
[image]http://publishingwithwordpress.com/wp-content/uploads/2014/06/06-do-ssh-entry-1024×340.png[/image][/galleria]

Creating a droplet only takes a minute. Digital Ocean will email you your IP address and root password.

Once you have your IP address, you can begin the process of mapping your domains and subdomains e.g. yourdomain.com to your IP address. Visit your domain registrar’s DNS settings and change the A record for your birdcage.yourdomain.com to the new IP address e.g. 54.234.124.117.

Wait until your DNS changes propagate (sometimes up to 24 hours or more – check them here), try to connect via SSH using your domain and the password provided in the Digital Ocean email.

ssh root@yourhostname.com

You can also use your IP address until your domain name is active:

ssh root@xx.xx.xx.xx

Change your password when prompted, or use:

passwd

There are a few things you’ll want to do to get your droplet ready for installing Birdcage.

sudo apt-get install zip php5-curl
sudo apt-get update
sudo apt-get upgrade
sudo a2enmod rewrite

It’s also best to run through the script for securing your MySQL server installation:

mysql_secure_installation

You might also wish to install PHPMyAdmin as I’ve described in Installing and Using PHPMyAdmin for Web Development.

Installing Birdcage

Installing Birdcage is relatively straightforward. Sign in to your Droplet via SSH as shown above. Download the code:

cd /var/www/
wget https://github.com/newscloud/birdcage/archive/master.zip
unzip master.zip
mv birdcage-master birdcage

Set the file privileges and permissions for Birdcage’s directories:

chown -R www-data:www-data birdcage
sudo find /var/www/birdcage/ -type d -exec chmod 755 {} \;
sudo find /var/www/birdcage/ -type f -exec chmod 644 {} \;
chmod -vR 0777 /var/www/birdcage/app/assets/
chmod -vR 0777 /var/www/birdcage/app/protected/runtime
chmod -vR 0777 /var/www/birdcage/app/protected/uploads
chmod 755 /var/www/birdcage/app/protected/yiic
chmod 755 /var/www/birdcage/app/protected/yiic.bat
chmod 755 /var/www/birdcage/app/protected/yiic.php

Login to MySQL. The password for your MySQL Server is usually shown when you login to your Droplet.

mysql -u root -p

Create a database for Birdcage and grant permissions:

create database birdcage;
grant all privileges on birdcage.* TO "root"@"localhost" identified by "your-password";
flush privileges;
exit;

You’ll have to provide these database settings in twitter.ini file. Copy the /app/docs/sample-config.ini to a secure directory on your server. e.g.

mkdir /var/secure
cp /var/www/birdcage/app/docs/sample-config.ini /var/secure/twitter.ini
nano /var/secure/twitter.ini

Then, change the database settings for your MySQL server:

mysql_host="localhost"
mysql_un="root"
mysql_db="basedev"
mysql_pwd="sql-user"

To build the MySQL database, we’ll run Yii ActiveRecord migrations:

cd /var/www/birdcage
./app/protected/yiic migrate up

You’ll be prompted to create your web user login credentials; you’ll use these to log in to the Birdcage website later:

Admin login [admin]: your-username
Admin email [webmaster@example.com]: admin@yourdomain.com
Admin password [admin]: supereasy99

Yii will then go ahead and build the database for you.

Next, we’ll create an Apache configuration file for the Birdcage website:

nano /etc/apache2/sites-available/birdcage.conf

Paste in the following – replace your sub-domain or domain name:

<VirtualHost *:80>
 ServerName birdcage.yourdomain.com
 DocumentRoot /var/www/birdcage/app
 DirectoryIndex index.php
 <Directory /var/www/birdcage/app/>
 AllowOverride All
 Order Deny,Allow
 Allow from all
 </Directory>
</VirtualHost>

Activate the site and reload Apache:

a2ensite birdcage.conf
a2dissite 000-default.conf 
service apache2 reload

We’ll use cron to configure a background task to regularly update Twitter via the REST API:

crontab -e

Paste in the following line – replace your domain (this will update your timeline every five minutes):

*/5 * * * * wget -O /dev/null http://birdcage.yourdomain.com/daemon/index

Visit your website e.g. http://birdcage.yourdomain.com and you should be able to login using your username and password from the migration.

Registering Your Application with Twitter

Follow the instructions in the Tuts+ tutorial for registering your application with Twitter to obtain your application API key and secret. You’ll need to set these up in the settings screen. You’ll need to visit Twitter’s App dashboard to register your application. Then, return to Birdcage to enter your settings:

Configure the OAuth Twitter API keys

Note: When you set up your app with twitter, the callback URL will be http://birdcage.yourdomain.com/twitter/callback. When you configure your settings with Birdcage above,  use http://birdcage.yourdomain.com/twitter, not the callback.

Configuring Your Twitter Account

Visit the Accounts menu and click Add Your Twitter account. Click the Twitter icon for your account and authorize your application to connect to your Twitter account. You can also follow the instructions in part two of the tutorial.

Click the Fetch menu to test that Birdcage is operating. You should see Tweets coming in. To switch to the Twitter Stream API with Phirehose, follow the instructions in part three of the tutorial.

Congratulations! You now have your own PHP-based Twitter API Framework applet to experiment on. If you’d like to go further, please check out my Birdhouse application.