Install Birdhouse

Building with the Twitter API

Birdhouse Installation Guide

This guide walks you through installing Birdhouse 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 Birdhouse 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 Birdhouse 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. 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:


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]×576.png[/image][image]×767.png[/image]

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. to your IP address. Visit your domain registrar’s DNS settings and change the A record for your to the new IP address e.g.

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.


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:


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

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:


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

Installing Birdhouse

Installing Birdhouse is relatively straightforward. Sign in to your Droplet via SSH as shown above. Once you’ve downloaded the purchased code, you can transfer it to your server with SCP, you may need to slightly adjust the filenames and directories based on your environment:

cd ~/Downloads
scp -r ./

Then, you’ll need to ssh in to your server and unzip the code to install it:

mv birdhouse-master birdhouse

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

chown -R www-data:www-data birdhouse
sudo find /var/www/birdhouse/ -type d -exec chmod 755 {} \;
sudo find /var/www/birdhouse/ -type f -exec chmod 644 {} \;
chmod -vR 0777 /var/www/birdhouse/app/assets/
chmod -vR 0777 /var/www/birdhouse/app/protected/runtime
chmod -vR 0777 /var/www/birdhouse/app/protected/uploads
chmod 755 /var/www/birdhouse/app/protected/yiic
chmod 755 /var/www/birdhouse/app/protected/yiic.bat
chmod 755 /var/www/birdhouse/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 Birdhouse and grant permissions:

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

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/birdhouse/app/docs/sample-config.ini /var/secure/twitter.ini
nano /var/secure/twitter.ini

Then, change the database settings for your MySQL server:

# important - some code dependencies currently with table prefix, set to tw_

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

cd /var/www/birdhouse
./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 Birdhouse website later:

Admin login [admin]: your-username
Admin email []:
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 Birdhouse website:

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

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

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

Activate the site and reload Apache:

a2ensite birdhouse.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
55 * * * * wget -O /dev/null
35 1 * * * wget -O /dev/null

Visit your website e.g. and you should be able to login using your username and password from the migration.

Registering Your Application with Twitter

You’ll need to visit Twitter’s App dashboard to register your application. You can follow the instructions in the Tuts+ tutorial for registering your application with Twitter to obtain your application API key and secret. Then, return to Birdhouse to enter your settings:

Configure the OAuth Twitter API keys

Note: When you set up your app with twitter, the callback URL will be When you configure your settings with Birdhouse above,  use, 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 account menu, update stream to test that Birdhouse 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 or do the following.

Edit the ini file again:

nano /var/secure/twitter.ini

Then, configure the stream variables to the account you wish to activate:

twitter_stream = true
twitter_stream_name = "reifman"

Then, from the console, activate the Stream command using nohup (no hangup):

nohup php ./app/stream.php Stream > /dev/null 2>&1&

While the stream will immediately capture data, it is quickly cached and won’t be uploaded til the next 5 minute interval that activates CRON tasks.

Congratulations! You now have your own PHP-based Twitter API Framework applet to experiment on.

Leave a reply

Your email address will not be published. Required fields are marked *