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.

The Rails 3 tutorial can be found here.

You will always go through the same steps when you create a new Shopify application to deploy 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 will 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.

Create a new Rails application

Generate the default directory structure for your new Shopify application using the rails 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 appname

Install the shopify_app plugin

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

$ cd appname

The shopify_app plugin is hosted on github.

Go to the shopify_app project homepage at http://github.com/Shopify/shopify_app.

Copy the Public Clone URL of the plugin to your clipboard:

Paste the Public Clone URL in the following Rails command in your Ruby console:

$ ruby script/plugin install git://github.com/Shopify/shopify_app.git

Install the shopify_api gem

(Note the difference between these: the shopify_app plugin and the shopify_api gem. Not the same.)

Open the file /config/environment.rb in your text editor. Add this code near Line 22:

config.gem 'shopify_api'

Save.

Then, in your application root folder (that's where your application rake file is), type in this command in your Ruby console:

rake gems:install

Questions and answers

Question: When I installed the shopify_app plugin it told me to run sudo gem install shopify_api. What gives?

Answer: Yes, sorry. We will change these instructions. That would work too, but it is not considered best practices. Editing the environment.rb is the usual Rails way to specify gem dependencies.

Add a manifest file for Heroku's sake specifying that you need the shopify_api gem

In the root of your application's folder, create a .gems (dot gems) file and add this 1 line of text to it:

shopify_api

That's it. Save.

Note

• For more information about gems management on Heroku (i.e. to clutter your brain perhaps), head over to the Managing gems page.

Questions and answers

Question: The environment.rb file already says I need shopify_api. Aren't we being redundant?

Answer: Heroku enforces the use of these manifest files. The .gems file tells Heroku where to get the gem (when its location is not on rubyforge/gemcutter), what version of the gem to use, etc. In our case, shopify_api is hosted on gemcutter, so we don't need to specify a 'source' in the .gems file.

Generate your Shopify application

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

$ ruby script/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.

Start your application

$ ruby script/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

We don't want our API key and shared secret to be part of any future deployment to a remote server, so we'll create a .gitignore file in the root of our application and add this line of text to it:

config/shopify.yml

In a new console, move to your application folder and do your first commit.

cd /c/Projects/appname
git init && git add . && git commit -m "Generated my application using the shopify_app plugin. I also added 'config.gem 'shopify_api' to environment.rb. That's it. I need cereals."

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:

cd /c/Projects/appname
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.

The single most important how-to page for you to read on Heroku is page 4 of 'How it Works': http://heroku.com/how/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.

Communicate 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.

Before we push our code to Heroku though...

Set your API key and shared secret as Config vars on Heroku

The shopify_app plugin has made it easy for you to add Config vars to Heroku: when installed, it has generated the comand line for this task, which you can simply copy and paste into your console. No need to type anything at all. Open the file /config/shopify.yml in your text editor and read the comments. The command is constructed like so:

heroku config:add SHOPIFY_API_KEY=<API KEY> SHOPIFY_API_SECRET=<SHARED SECRET>

Make sure that you have moved to the root of your app folder when you execute the command. These Config vars are application-specific.

Heroku will restart your application.

Note

• Your API key and secret are the same in development as they are in production.

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.

Note

• While you push your code to Heroku, if you're on a Mac, you may see a message asking you: The authenticity of host 'heroku.com (174.129.212.2)' can't be established. Are you sure you want to continue connecting? Type in: yes.

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 to make sure that they are correct.