Last updated August 25, 2022

Facebook offers a rich set of APIs and several SDKs, making it easy to develop applications that interact with Facebook data and services. Such applications can be developed and deployed to Heroku, in any of Heroku’s supported languages.

This guide is for Facebook developers who develop and deploy their applications on Heroku.

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.

Prerequisites

• Basic Facebook app creation knowledge
• Basic Git knowledge
• A Heroku account

Local workstation setup

Install the Heroku CLI on your local workstation. This ensures that you have access to the Heroku command-line client.

Once installed, you use the heroku command from your command shell. Log in using the email address and password you used when creating 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.

Workflow

There are four components to creating a Facebook application:

• Creating the Facebook app on Facebook’s App Dashboard
• Writing the source code for your app and deploying it to Heroku
• Configuring the Heroku app to hold the Facebook App ID and Secret
• Modifying the settings for your Facebook app to reference the Heroku app

Creating the Facebook app

Visit Facebook’s App Dashboard to create a new application. Click on “Create New App”.

After providing the app with a name and filling in the captcha, you’ll be placed into the settings area for the application. You’ll also be provided with an App ID and App Secret that will be needed later.

Creating the Heroku app

While we can’t write your app for you, this guide uses a simple demo Ruby app to illustrate the process. You can of course develop your Facebook app in any other language supported on Heroku, such as Java, Python or Node.js. Refer to the Facebook SDK documentation to find a suitable library for your language of choice - the general method of developing and deploying on Heroku is the same for each language.

As a quick start, clone this demo Ruby application:

$ git clone https://github.com/jonmountjoy/facebook-template-ruby
$ cd facebook-template-ruby

Now create the Heroku application:

$ heroku create
$ Creating radiant-tor-1481 in organization heroku... done, region is us
  http://radiant-tor-1481.herokuapp.com/ | git@heroku.com:radiant-tor-1481.git

Note the URL of the application.

Now deploy the app source code to Heroku:

$ git push heroku master

Configure the Heroku app

This demo app, like most Heroku apps, uses config vars to store external, configuration information about the app. These config vars will be made available to the app at run time as ordinary environment variables. This app template uses two - the Facebook App ID and App Secret - which any Facebook app requires.

Set the config vars. Reference your Facebook application for the App ID and App Secret:

$ heroku config:set FACEBOOK_APP_ID=133333333463066  \
                  FACEBOOK_SECRET=a7244e333333333a7a2bf9492a6089a0

Note how the application uses these config vars when authenticating against the Facebook API:

def authenticator
    @authenticator ||= Koala::Facebook::OAuth.new(ENV["FACEBOOK_APP_ID"], ENV["FACEBOOK_SECRET"], url("/auth/facebook/callback"))
end

Configure the Facebook app

When you created the Facebook application, you were assigned a Heroku app name and a resulting URL - in this case it was http://radiant-tor-1481.herokuapp.com.

Take your Heroku app’s URL (run heroku info if you’ve lost it) and configure your Facebook application to use it.

• Click on “Settings”
• Click “Add Platform”
• Select “Website”
• Insert the Heroku app’s URL in the “Site URL” field, and save the changes.

At this point you should have a working application. Navigate to your Heroku app, or execute this from the command line:

$ heroku open

Congratulations! You now have your very own Facebook app, running on Heroku:

The demo 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.

Editing your app

With your Heroku account and local tools set up, you can start making changes to your Facebook app.

1) 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 index.erb, in the views folder:

<p>Welcome to your Facebook app, running on <span>heroku</span>!</p>

Use your favorite text editor to change this line to:

<p>This is my app, I can edit it all I want.</p>

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(-)

2) 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), 291 bytes | 0 bytes/s, done.
Total 3 (delta 2), reused 0 (delta 0)

-----> Ruby/Rack app detected
-----> Using Ruby version: ruby-1.9.3
-----> Installing dependencies using Bundler version
...
       Using json (1.5.5)
       Using multi_json (1.0.3)
       Using koala (1.3.0)
       Using tilt (1.3.3)
       Using sinatra (1.2.6)
       Your bundle is complete! It was installed into ./vendor/bundle
       Cleaning up the bundler cache.
-----> Discovering process types
       Procfile declares types     -> web
       Default types for Ruby/Rack -> console, rake

-----> Compiled slug size: 14.5MB
-----> Launching... done, v7
       http://radiant-tor-1481.herokuapp.com deployed to Heroku

To git@heroku.com:radiant-tor-1481.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, but typically you would use heroku local, installed as part of the Heroku CLI, to start the application.

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 settings for the 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://localhost:5000/.

To set up this second app, go to Facebook App Dashboard 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 environment variables

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, you added these to your Heroku app as config vars, but in your local environment you’ll need to set them as environment variables.

heroku local automates this local environment configuration. It will automatically source a file named .env in the root of your app’s code checkout when it runs your app. Cut-and-paste your App ID and App Secret into .env:

 FACEBOOK_APP_ID=964173273189
 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.

Further reading

• How Heroku Works
• Facebook Developer Docs
• Facebook Graph API Docs