Getting Started with Your Facebook App on Heroku
Last Updated: 15 November 2011
facebook
Table of Contents
Create an App
What is Heroku?
Heroku Account and Tools Setup
Editing Your App
Working Locally
Further Reading
This guide is for Facebook developers who are creating apps on Heroku via the Facebook Cloud Services integration.
It assumes no previous knowledge of Heroku, and will walk through every part of the process: creating an app and a Heroku account, setting up local development tools, and deploying changes to your Facebook app.
Create an App
(If you’ve already created a Heroku app via Facebook, you can skip to the next section.)
Start by going to Facebook Developers and clicking Create New App in the upper-right corner:
You’ll be presented with this dialog:
Enter anything you wish for the app name, check the terms box, then click Continue.
Fill out the captcha in the subsequent dialog and click Submit. After a brief delay you’ll be taken to your (currently blank) Facebook app settings page. Look for the Cloud Services section:
Click the Get Started button, taking you here:
Heroku is the only option in this dialog, so click Next.
If you already have a Heroku account for the email address you enter, the new app will be associated with your existing account.
Choose your favorite programming language from the dropdown (Ruby, Node.js, Python, and PHP are currently available). Enter the email address you wish to use for your Heroku user account, then click Create.
You’ll be taken to a success dialog:
A template app, written in the language you chose, has been copied and deployed just for you!
Click Go to app to visit your new app.
Other users visiting your app will need to grant permission via a similar dialog. Users only need to do this the first time they visit the app.
Because you’re visiting your app as a user, you need to grant permission for the app to access your Facebook profile by clicking Allow:
Congratulations! You now have your very own Facebook app, running on Heroku:
By default, your new app is configured as a website that integrates with Facebook. This means it will display as a standalone page. If you’d like your app to run as a canvas page inside the Facebook chrome, follow this guide.
The app shows examples of accessing the Facebook API to list friends, photos, interests, and more. Once you start editing the code, you can use these capabilities to make your app do more interesting things.
Now that you’ve got a running app, you’ll want to start editing it. But first, a brief aside.
What is Heroku?
(If you’re already familiar with Heroku, you can skip to the next section.)
Your Facebook app needs to run somewhere. This can be traditional hosting such as your own hardware or a VPS; however, these options are time-consuming and costly to set up. Apps on Heroku can be created instantly, and they cost you nothing unless the app grows to a large amount of traffic or users.
Heroku is a cloud application platform. With Heroku, you don’t need to think about servers at all. You can write apps in the programming language of your choice, back it with add-on resources such as SQL and NoSQL databases, Memcached, and many others. You manage your app using the Heroku command-line tool and you deploy code using the Git revision control system, all running on the powerful Heroku infrastructure.
Any kind of web app can be deployed to Heroku; you can read all about the platform’s capabilities in the Dev Center. For the rest of this guide, we’ll focus on editing the Facebook app you’ve already created in the previous section.
Heroku Account and Tools Setup
(If you already have a Heroku account and the local development tools set up, you can skip to the next section.)
Although an account as already been created for you, and the app has already been deployed, you still need to create a password and set up local tools to make changes to it.
1) Choose a Password
A Heroku user account was created for you when you created the app through Facebook. Check your email and look for the welcome message:
Follow the first link in that email to the page where you can choose a password for your Heroku account:
Create a password, then close that browser window and proceed to the next step.
2) Install the Heroku Toolbelt
To manage and edit your app, you’ll need the Heroku command-line tool and the Git revision control system, both of which will be installed by the Heroku toolbelt. Download and install the toolbelt for your OS from the list below:If you have... Install with...
Mac OS X Download OS X package
Windows Download Windows .exe installer
Ubuntu Linux apt-get repository
Other Tarball (add contents to your $PATH)
3) Log In from the Command Line
Once installed, you’ll have access to the heroku command from your terminal (use cmd.exe on Windows). Log in using the email address and password for your Heroku account:
$ heroku login
Enter your Heroku credentials.
Email: adam@example.com
Password:
Could not find an existing public key.
Would you like to generate one? [Yn]
Generating new SSH public key.
Uploading ssh public key /Users/adam/.ssh/id_rsa.pub
Press enter at the prompt to upload your existing ssh key or create a new one, used for pushing code later on.
Editing Your App
With your Heroku account and local tools set up, you can start making changes to your Facebook app.
1) Fetch Your App’s Sourcecode
We’ll start by grabbing a copy of your app’s sourcecode using Git. You’ll need to know the name of your app for this: Heroku gave it a randomly-generated haiku name to start with, so look in the URL to find your app name. For example, if your URL is https://furious-robot-218.herokuapp.com, then your app name is furious-robot-218. Paste this into a git clone command like so:
$ git clone git@heroku.com:furious-robot-218.git -o heroku
Initialized empty Git repository in /Users/adam/facebook-template-php/.git/
remote: Counting objects: 273, done.
remote: Compressing objects: 100% (183/183), done.
remote: Total 273 (delta 2), reused 261 (delta 0)
Receiving objects: 100% (273/273), 25.55 KiB, done.
Resolving deltas: 100% (2/2), done.
cd into the directory created by the git clone operation, which will be named the same thing as the app (e.g. furious-robot-218).
2) Make a Change
Let’s tweak something small in the app and push it back up to Heroku, illustrating the deploy process. For example, find the line of HTML which shows the welcome banner (in the PHP app, index.php line 157):
Welcome to your Facebook app, running on heroku!
Use your favorite text editor to change this line to:
This is my app, I can edit it all I want.
Save the file, then use your terminal to commit the change to Git:
$ git commit -am "changed greeting"
[master 0ff313a] changed greeting
1 files changed, 1 insertions(+), 1 deletions(-)
3) Deploy to Heroku
Now, the fun part – pushing the modified code up to Heroku with git push heroku master:
$ git push heroku
Counting objects: 5, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 347 bytes, done.
Total 3 (delta 1), reused 0 (delta 0)
-----> Heroku receiving push
-----> PHP app detected
-----> Bundling Apache... done, v2.2.19
-----> Bundling PHP... done, v5.3.6
-----> Discovering process types
Procfile declares types -> (none)
Default types for PHP -> web
-----> Compiled slug size is 20.9MB
-----> Launching... done, v2
http://furious-robot-218.herokuapp.com deployed to Heroku
To git@heroku.com:furious-robot-218.git
396ec84..994290d master -> master
Reload the app in your browser. You should see the modified welcome banner:
Congratulations, you’re now a Facebook app developer!
You can now go to work on your application. When you’re ready to get more advanced in your editing techniques, move on to the next section.
Working Locally
In the previous section, we pushed changes to the app to the live production environment without testing it in a local environment. A better workflow is running the app locally, and testing your changes there. When you’re ready to deploy, use git commit and git push heroku to push up changes to the live production app.
Methods for running your app on your local computer will vary by programming language and operating system. For example, PHP developers on Mac OS X can use the version of Apache and PHP that comes with the operating system by configuring a VirtualHost in their Apache config. Ruby developers, on the other hand, may run their app with Foreman.
Regardless of how you run your app locally, there are two techniques you’ll need to know about that are specific to running a local development version of a Facebook app.
1) Creating a Development Facebook App
The Facebook app you previously created points at the URL of your Heroku app (which will look like https://furious-robot-218.herokuapp.com). This is the production app.
For development, you’ll need to register another app with Facebook. Unlike the first app, this one will not run on Heroku, but instead will run on your local workstation and have a URL like http://127.0.0.1:5000/.
To set up this second app, go to Facebook Developers and again click Create New App. Choose a name to indicate that this is the development version of your existing app. For example, if your other app is named “My Cool App”, you might call this one “My Cool App - Dev”.
Once created, click the Website checkbox and enter your local URL. For example:
The click Save Changes.
2) Setting Facebook App Env Vars
On the same settings page for your app used to set the website URL, you’ll also find the App ID and App Secret:
For your production app, these were automatically added to your Heroku app as config vars, but in your local environment you’ll need to set them as environment variables. How you’ll set env vars depends on your OS and method of running your app. Here are two examples:
Foreman .env
If you run your app with Foreman, it will automatically source a file named .env in the root of your app’s code checkout. Cut-and-paste your App ID and App Secret into .env:
FACEBOOK_APP_ID=964173273189
FACEBOOK_SECRET=dcd5d23d003d53cb2b68e01
Apache SetEnv
If you’re running your app with Apache, you can set the env vars for your local app’s VirtualHost using the SetEnv directive. For example:
DocumentRoot /Users/adam/Sites/mycoolapp-dev
ServerName mycoolapp-dev.localhost
SetEnv FACEBOOK_APP_ID 964173273189
SetEnv FACEBOOK_SECRET dcd5d23d003d53cb2b68e01
Ready to Test Locally
With these two changes in place, you should be able to visit your app locally and access all Facebook functionality. When you’re ready to share your changes in the world, git commit them and then git push heroku, then visit your production app to confirm that your changes work correctly on the live app.
Last Updated: 15 November 2011
Table of Contents
Create an App
What is Heroku?
Heroku Account and Tools Setup
Editing Your App
Working Locally
Further Reading
This guide is for Facebook developers who are creating apps on Heroku via the Facebook Cloud Services integration.
It assumes no previous knowledge of Heroku, and will walk through every part of the process: creating an app and a Heroku account, setting up local development tools, and deploying changes to your Facebook app.
Create an App
(If you’ve already created a Heroku app via Facebook, you can skip to the next section.)
Start by going to Facebook Developers and clicking Create New App in the upper-right corner:
You’ll be presented with this dialog:
Enter anything you wish for the app name, check the terms box, then click Continue.
Fill out the captcha in the subsequent dialog and click Submit. After a brief delay you’ll be taken to your (currently blank) Facebook app settings page. Look for the Cloud Services section:
Click the Get Started button, taking you here:
Heroku is the only option in this dialog, so click Next.
If you already have a Heroku account for the email address you enter, the new app will be associated with your existing account.
Choose your favorite programming language from the dropdown (Ruby, Node.js, Python, and PHP are currently available). Enter the email address you wish to use for your Heroku user account, then click Create.
You’ll be taken to a success dialog:
A template app, written in the language you chose, has been copied and deployed just for you!
Click Go to app to visit your new app.
Other users visiting your app will need to grant permission via a similar dialog. Users only need to do this the first time they visit the app.
Because you’re visiting your app as a user, you need to grant permission for the app to access your Facebook profile by clicking Allow:
Congratulations! You now have your very own Facebook app, running on Heroku:
By default, your new app is configured as a website that integrates with Facebook. This means it will display as a standalone page. If you’d like your app to run as a canvas page inside the Facebook chrome, follow this guide.
The app shows examples of accessing the Facebook API to list friends, photos, interests, and more. Once you start editing the code, you can use these capabilities to make your app do more interesting things.
Now that you’ve got a running app, you’ll want to start editing it. But first, a brief aside.
What is Heroku?
(If you’re already familiar with Heroku, you can skip to the next section.)
Your Facebook app needs to run somewhere. This can be traditional hosting such as your own hardware or a VPS; however, these options are time-consuming and costly to set up. Apps on Heroku can be created instantly, and they cost you nothing unless the app grows to a large amount of traffic or users.
Heroku is a cloud application platform. With Heroku, you don’t need to think about servers at all. You can write apps in the programming language of your choice, back it with add-on resources such as SQL and NoSQL databases, Memcached, and many others. You manage your app using the Heroku command-line tool and you deploy code using the Git revision control system, all running on the powerful Heroku infrastructure.
Any kind of web app can be deployed to Heroku; you can read all about the platform’s capabilities in the Dev Center. For the rest of this guide, we’ll focus on editing the Facebook app you’ve already created in the previous section.
Heroku Account and Tools Setup
(If you already have a Heroku account and the local development tools set up, you can skip to the next section.)
Although an account as already been created for you, and the app has already been deployed, you still need to create a password and set up local tools to make changes to it.
1) Choose a Password
A Heroku user account was created for you when you created the app through Facebook. Check your email and look for the welcome message:
Follow the first link in that email to the page where you can choose a password for your Heroku account:
Create a password, then close that browser window and proceed to the next step.
2) Install the Heroku Toolbelt
To manage and edit your app, you’ll need the Heroku command-line tool and the Git revision control system, both of which will be installed by the Heroku toolbelt. Download and install the toolbelt for your OS from the list below:If you have... Install with...
Mac OS X Download OS X package
Windows Download Windows .exe installer
Ubuntu Linux apt-get repository
Other Tarball (add contents to your $PATH)
3) Log In from the Command Line
Once installed, you’ll have access to the heroku command from your terminal (use cmd.exe on Windows). Log in using the email address and password for your Heroku account:
$ heroku login
Enter your Heroku credentials.
Email: adam@example.com
Password:
Could not find an existing public key.
Would you like to generate one? [Yn]
Generating new SSH public key.
Uploading ssh public key /Users/adam/.ssh/id_rsa.pub
Press enter at the prompt to upload your existing ssh key or create a new one, used for pushing code later on.
Editing Your App
With your Heroku account and local tools set up, you can start making changes to your Facebook app.
1) Fetch Your App’s Sourcecode
We’ll start by grabbing a copy of your app’s sourcecode using Git. You’ll need to know the name of your app for this: Heroku gave it a randomly-generated haiku name to start with, so look in the URL to find your app name. For example, if your URL is https://furious-robot-218.herokuapp.com, then your app name is furious-robot-218. Paste this into a git clone command like so:
$ git clone git@heroku.com:furious-robot-218.git -o heroku
Initialized empty Git repository in /Users/adam/facebook-template-php/.git/
remote: Counting objects: 273, done.
remote: Compressing objects: 100% (183/183), done.
remote: Total 273 (delta 2), reused 261 (delta 0)
Receiving objects: 100% (273/273), 25.55 KiB, done.
Resolving deltas: 100% (2/2), done.
cd into the directory created by the git clone operation, which will be named the same thing as the app (e.g. furious-robot-218).
2) Make a Change
Let’s tweak something small in the app and push it back up to Heroku, illustrating the deploy process. For example, find the line of HTML which shows the welcome banner (in the PHP app, index.php line 157):
Welcome to your Facebook app, running on heroku!
Use your favorite text editor to change this line to:
This is my app, I can edit it all I want.
Save the file, then use your terminal to commit the change to Git:
$ git commit -am "changed greeting"
[master 0ff313a] changed greeting
1 files changed, 1 insertions(+), 1 deletions(-)
3) Deploy to Heroku
Now, the fun part – pushing the modified code up to Heroku with git push heroku master:
$ git push heroku
Counting objects: 5, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 347 bytes, done.
Total 3 (delta 1), reused 0 (delta 0)
-----> Heroku receiving push
-----> PHP app detected
-----> Bundling Apache... done, v2.2.19
-----> Bundling PHP... done, v5.3.6
-----> Discovering process types
Procfile declares types -> (none)
Default types for PHP -> web
-----> Compiled slug size is 20.9MB
-----> Launching... done, v2
http://furious-robot-218.herokuapp.com deployed to Heroku
To git@heroku.com:furious-robot-218.git
396ec84..994290d master -> master
Reload the app in your browser. You should see the modified welcome banner:
Congratulations, you’re now a Facebook app developer!
You can now go to work on your application. When you’re ready to get more advanced in your editing techniques, move on to the next section.
Working Locally
In the previous section, we pushed changes to the app to the live production environment without testing it in a local environment. A better workflow is running the app locally, and testing your changes there. When you’re ready to deploy, use git commit and git push heroku to push up changes to the live production app.
Methods for running your app on your local computer will vary by programming language and operating system. For example, PHP developers on Mac OS X can use the version of Apache and PHP that comes with the operating system by configuring a VirtualHost in their Apache config. Ruby developers, on the other hand, may run their app with Foreman.
Regardless of how you run your app locally, there are two techniques you’ll need to know about that are specific to running a local development version of a Facebook app.
1) Creating a Development Facebook App
The Facebook app you previously created points at the URL of your Heroku app (which will look like https://furious-robot-218.herokuapp.com). This is the production app.
For development, you’ll need to register another app with Facebook. Unlike the first app, this one will not run on Heroku, but instead will run on your local workstation and have a URL like http://127.0.0.1:5000/.
To set up this second app, go to Facebook Developers and again click Create New App. Choose a name to indicate that this is the development version of your existing app. For example, if your other app is named “My Cool App”, you might call this one “My Cool App - Dev”.
Once created, click the Website checkbox and enter your local URL. For example:
The click Save Changes.
2) Setting Facebook App Env Vars
On the same settings page for your app used to set the website URL, you’ll also find the App ID and App Secret:
For your production app, these were automatically added to your Heroku app as config vars, but in your local environment you’ll need to set them as environment variables. How you’ll set env vars depends on your OS and method of running your app. Here are two examples:
Foreman .env
If you run your app with Foreman, it will automatically source a file named .env in the root of your app’s code checkout. Cut-and-paste your App ID and App Secret into .env:
FACEBOOK_APP_ID=964173273189
FACEBOOK_SECRET=dcd5d23d003d53cb2b68e01
Apache SetEnv
If you’re running your app with Apache, you can set the env vars for your local app’s VirtualHost using the SetEnv directive. For example:
DocumentRoot /Users/adam/Sites/mycoolapp-dev
ServerName mycoolapp-dev.localhost
SetEnv FACEBOOK_APP_ID 964173273189
SetEnv FACEBOOK_SECRET dcd5d23d003d53cb2b68e01
Ready to Test Locally
With these two changes in place, you should be able to visit your app locally and access all Facebook functionality. When you’re ready to share your changes in the world, git commit them and then git push heroku, then visit your production app to confirm that your changes work correctly on the live app.
Comments