Creating an app and deploying it to Heroku using Rails 3
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:
- 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
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.
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:
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:
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> email@example.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.
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.
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.
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.