From Shopify Wiki

This tutorial is out of date. For up-to-date instructions on creating a Shopify app with Rails, visit the shopify_app GitHub repo.

You will always go through the same steps when you create a new Shopify application to deploy to Heroku.

If you're still using Rails 2, head over here: Creating an app and deploying it to Heroku.

Are you ready for this? (Resources)

• To deploy your Shopify application to Heroku, you will need to use git. Know your way around git. All you need to learn about git is presented in plain English in this tutorial: Easy Version Control with Git

• Learn the basics about the ActiveResource::Base class. Go over the ActiveResource:Base API page and bookmark it for future reference. Don't skip these sections: Automated mapping, Lifecycle methods (skip over the custom methods), Authentication, Public Class methods, Public Instance methods.

• Watch these two railscasts to get comfortable with ActiveResource: ActiveResource Basics and More on ActiveResource

• Browse the Shopify API: API Docs Introduction

• Read this page about Shopify authentication all the way through at least once: Shopify API Authentication

Register your application

To get your API key and your shared secret, register your application at https://app.shopify.com/services/partners.

First screen of the multipage creation form:

Notes

• You will need to determine from the get go if your application will require read and write access, or just read access. See note 4 in the screen capture above.

• The Return URL for your app should be until deployment: http://localhost:3000/login/finalize See note 5 in the screen capture above.

On the 2nd screen of the multipage creation form, just save:

On the third and final page, the registration process has been finalized. Leave your browser tab open and move on to the next step. Note in the screen capture below that you have access to 3 very important bits of information: your API key, your secret and your Return URL. You will refer to those later.

Questions and answers

Question: Do I need to become a Shopify partner to create a Shopify application?

Answer: Yes, dear. If you want your app to be used by many shops, yes. Even if you need your app to be used by 1 shop only, if you need to add links to a shop's admin pages then you'll still need a partner account to create your app.

If you don't care about adding links to a shop's admin pages, and if you don't care to have your app used by more than 1 shop, then you are welcome to create what's called a private application (aka 'private app').

Create a new Rails application

Generate the default directory structure for your new Shopify application using the rails new command in your Ruby console. (On the Mac, you launch the Terminal application, and on Windows you are most likely opening an Instant Rails console for this.)

$ rails new appname

I use Ruby Version Manager on my Mac, so when I want to create a Rails 3 app, I switch over to my Rails 3 environment using this command:

$ rvm use 1.9.2

Then, I run this sanity check:

$ rails - v
Rails 3.0.0

Then, I create my new app.

Install the shopify_app generator

Move inside the folder of your new application to install the shopify_app generator gem.

$ cd appname

Add the shopify_app gem to your application's Gemfile:

$ echo "gem 'shopify_app'" >> Gemfile

Install your application's gems:

$ bundle install

If the bundle install command is not found, install it with

sudo gem install bundler

or

gem install bundler

if you’re using RVM.

Generate your Shopify application

Use the generator provided by the shopify_app gem to generate your application:

$ rails generate shopify_app <API KEY> <SHARED SECRET>

Replace the <API KEY> and <SHARED SECRET> with the ones provided for your application.

Go to the browser tab that we had left open in Step 1. Use copy and paste.

Note

You'll be asked if you want to Overwrite /Users/<username>/<your-project-folder>/<app-name>/app/views/layouts/application.html.erb file. Type in 'Y' and press Enter.

Start your application

$ rails server

Install your app in a Test shop

Visit the welcome page of your new app at http://localhost:3000/.

You will be prompted to login and install the app for a particular store. You can create a Test Shop pre-filled with products and orders on this page: https://app.shopify.com/services/partners/api_clients/test_shops

When you install the app for your shop, you will see what the future users of your application will see:

The home page of the app that was generated for you looks like this:

Note

Make sure everything looks functional once you finally land on your app home page. Read the text in the right column. It's a common Shopify design pattern to place instructions in a right column, keep that in mind when you'll be polishing your app. As the saying goes: [checked]. Time to write some code. But first...

Make a first commit

Back in the console or Terminal, from your application folder, do your first commit:

git init && git add . && git commit -m "Generated my application using the shopify_app gem!"

Write some code

Time to write some code, perhaps generate a few controllers and models.

Whenever you reach a new milestone, make a git commit. The first time you make a commit, it's special. We covered that first command already. All subsequent commits should be done like so, with your own personalized message of course:

git commit -am "Here is what I added now. I did this and that. I rock."

After you've had your fun for a while, you may want to deploy a first alpha version on Heroku. That will allow your boyfriend or girlfriend to test your app on his/her computer.

Create an account on Heroku

It used to be by invite, now the door is wide open. It is still free to use for most needs.

Head over to Heroku. Create an account there or sign in.

Take a look at the 'How it Works' section for details on the Heroku workflow.

Install the heroku gem

You need to install the heroku gem only once. Can't remember if you did it before or not? See if you have it:

gem list heroku

If you don't have it installed yet, you will see the heading '*** LOCAL GEMS ***' with nothing listed below it.

Install or update your heroku gem:

sudo gem install heroku

gem update heroku

It may take a while to install, or update. Be patient.

Send your ssh key to Heroku

Once that's completed, communicate your id_rsa.pub key to Heroku with this command:

heroku keys:add

You will be prompted to type in your Heroku credentials. This is why you needed to create an account on Heroku to begin with.

Create an empty app holder on Heroku

Create your application 'cup holder' on Heroku:

heroku create my-app-name

The 'my-app-name' part will become the subdomain of your application on Heroku. You can change that later so no worries.

Heroku creates a git repository for your new application and gives you the git URL for it.

See that text: Git remote heroku added in your console? You won't need to do 'git remote add <name> git@heroku.com:my-app-name.git '. That's been done for you already.

Push your application to Heroku

Do a 'git status' to make sure that all your changes have been committed.

git status

Then push your application to your remote repository on Heroku:

git push heroku master

If you're pushing code from another branch than master, replace master with the name of the branch you're working on.

Change your Return URL

Go to your application page on the Shopify Partners site at: https://app.shopify.com/services/partners/api_clients/ and click on the Edit App button:

Modify the Return URL to point to your hosted application on Heroku:

Visit your app

Go to http://my-app-name.heroku.com and enjoy.

Troubleshooting

Log Files

If you get the screen 'We're sorry, but something went wrong' with a Internal Server Error (HTTP 500), this means that there is an error inside your application. Common causes are broken gem dependencies, syntax errors, and argument errors. Use “heroku logs” to diagnose the problem, and implement a fix.

heroku logs

Check your key and secret

If you deploy your app and it doesn't show the permission query, instead going straight to admin/apps after logging in (i.e your finalize method is not called), then double check your key and secret in config/application.rb to make sure that they are correct.