Install Birdcage
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:
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:
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.