Guides

1 This Guide Assumes

This guide is designed for beginners who want to get started with a Spree application from scratch. It assumes a basic working knowledge of Ruby on Rails. To get the most out of this guide, you need to have some prerequisites installed:

• The Ruby language
• The RubyGems packaging system
• The Ruby on Rails gems
• A working installation of SQLite (preferred), MySQL, or PostgreSQL

It is highly recommended that you familiarize yourself with Ruby on Rails before diving into Spree. You will find it much easier to follow what’s going on with a Spree application if you understand basic Ruby syntax.

There are many excellent online resources for learning Ruby on Rails, including:

• Rails Guides
• Railscasts

There are also some good free resources on the internet for learning Ruby, including:

• Mr. Neighborly’s Humble Little Ruby Book
• Programming Ruby
• Why’s (Poignant) Guide to Ruby

2 What is Spree?

Spree is a full featured commerce platform written for the Ruby on Rails framework. It is designed to make programming commerce applications easier by making several assumptions about what most developers needs to get started. Spree is a production ready store that can be used “out of the box”, but more importantly, it is also a developer tool that can be used as a solid foundation for a more sophisticated application than what is generally possible with traditional open source offerings.

Spree is open source. It is licensed under the very permissive New BSD License. You are free to use the software as you see fit, at no charge. Perhaps more important than the cost, Spree is a true open source community. Spree has hundreds of contributors who have used and improved it while building their own e-commerce solutions.

2.1 Motivation

The goal of the project is to build a complete open source commerce solution for Ruby on Rails. At the start of this project, the Rails commerce space was immature and lacking serious solutions for developers with complex business needs. In the past, Rails has suffered from “small project mentality.” Most open source projects in Rails are maintained by a single individual and tend to be limited in scope. Spree seeks to create a large and healthy open source community that developers of other languages have come to expect.

The founder of Spree was motivated to start the project after failing to find an existing community in the Rails space dedicated to this vision. In addition, he was motivated by unsuccessful efforts to use other open source solutions in other programming languages, including (but not limited to) the Magento and OSCommerce platforms. These solutions were deemed to be unsatisfactory when challenged with even the simplest practical cases of use. They were also written in PHP which was considered to be a poor choice for long term maintainability.

2.2 Opinionated Commerce

David Heinemeier Hansson (the creator of Rails) is well known for saying that Rails is “opinionated software.” Spree continues this fine tradition of adopting a few strong (possibly controversial) opinions which drive its development.

2.2.1 No Solution Will Satisfy Everyone

No solution can possibly solve everyone’s needs perfectly. There are simply too many ways in which people do business for us to tailor to each individual need. Rather than come up short (like so many projects before it did), Spree’s approach is to simply accept this and not even try. Instead Spree tries to focus on solving 90% of the bulk that most commerce projects face. The remaining 10% will need to be addressed by the end developer familiar with the client’s exact business requirements.

2.2.2 Online Commerce is not for “Noobs”

Rails developers are the target audience for this application – not business owners. No serious company would ever try to run an online store by just paying some fool on Craig’s List to install OSCommerce for them. Serious businesses have complicated needs that require paying one or more software professionals to solve them. Spree seeks to be the platform that developers use as the foundation for their project rather than having to start from scratch or settle for less with other software.

2.2.3 Developers Need Complete Control

Most business owners will not be satisfied with the generic templates offered by other platforms. Why should they? They want their website to look just like the other professional sites they see on the web. Most businesses have very specific shipping and taxation rules as well. Spree needs to be flexible enough to accommodate most situations. Sensible defaults should be provided with an eye towards allowing further customization.

2.2.4 Stay Focused

This is perhaps the most important principle behind the design philosophy. We need to stay focused on core functionality (the 90% that everybody needs.) For this reason it is not appropriate for Spree to attempt to become a Content Management System (CMS). There are already some pretty good Rails based CMS projects out there such as Radiant. CMS is definitely important but it is a big enough task to warrant its own project. Spree will definitely be looking at ways to integrate with existing CMS platforms, we just won’t be attempting to reinvent the CMS concept.

3 Prerequisites

If you follow this guide, you’ll create a Spree project called mystore, a (very) simple online store. Before you can start building the application, you need to make sure that you have Rails itself installed.

3.1 Installing Rails

In most cases, the easiest way to install Rails is to take advantage of RubyGems:

$ gem install rails -v 3.2.3

Support for Rails 3.1.x is dropped. Rails 3.2.x offers performance boost in development mode and is the first-class supported platform for 1.1.x release cycles. It is recommended that you use the latest version 3.2.3.

3.2 Installing Bundler

Bundler is the current standard for maintaining Ruby gem dependencies. It is recommended that you have a decent working knowledge of Bundler and how it used within Rails before attempting to install Spree. You can install Bundler using the following command:

$ gem install bundler

3.3 Installing Image Magick

Spree also uses the Image Magick library for manipulating images. Using this library allows for automatic resizing of product images and the creation of product image thumbnails. Image Magick is not a Rubygem and it can be a bit tricky to install. There are, however, several excellent sources of information on the Web for how to install it. A basic Google search should help you if you get stuck.

3.4 Installing the Spree Gem

Spree is distributed as a Rubygem. The Spree gem itself is actually very small and it depends on several other so-called “core gems.” Most users, however, will never need to worry about these individual gems and can simply install the spree gem.

$ gem install spree

If you get an “Unable to resolve dependencies” error while installing the Spree gem you can try installing just the spree_cmd gem instead (which has minimal dependencies.)

$ gem install spree_cmd

4 Creating a New Spree Project

The distribution of Spree as a Rubygem allows it to be used in a new Rails project or added to an existing Rails project. This guide will assume you are creating a brand new store and will walk you through the process starting with the creation of a new Rails application.

4.1 Creating the Rails Application

Let’s start by creating a standard Rails application using the following command:

rails new mystore

This creates a new Rails application using all of the default options (including a Sqlite3 database.) If you wish to create your application with a different database you can use the -d option (again this is not specific to Spree – it’s standard Rails at this point.)

For example, to create your application using Mysql you use the following command instead:

rails new mystore -d mysql

Here is a complete list of database options

• mysql
• oracle
• postgresql
• sqlite3
• frontbase
• ibm_db

4.2 Configuring the Database

Since Spree is a Rails application you can configure your database in the standard way. Please consult the Rails Guide for more information on database configuration.

4.3 Adding Spree to a Rails Application

Now that we have a basic Rails application we can add Spree to it. This approach would also work with existing Rails applications that have been around for a long time (assuming they are using the correct version of Rails.)

After you create the store application, switch to its folder to continue work directly in that application:

cd mystore

Now let’s add Spree to our Rails application:

spree install

Spree will then ask you a few questions about installing sample data, etc. It is recommended you hit ‘Enter’ and accept the default answers unless you know what you’re doing.

This will use the latest stable release of Spree. If you want to use the edge version of Spree or one of the other options consider one of the following commands instead.

# Use latest edge version of Spree
spree install --edge

#Using a local clone
spree install --path

#Using a GitHub clone
spree install --git=git@github.com:cmar/spree.git --branch=my_changes

#Answer yes to all questions
spree install --auto_accept

5 Hello, Spree!

5.1 Starting up Spree

You now have a functional Spree application after running only a few commands! In fact this application is essentially the same as the Spree demo that runs on demo.spreecommerce.com. To see it, you need to start a web server on your development machine. You can do this by running another command:

$ rails server

Alternatively you can use the shortcut:

$ rails s

This will fire up an instance of the Webrick web server by default (Spree can also use several other web servers). To see your application in action, open a browser window and navigate to http://localhost:3000. You should see the Spree default home page:

To stop the web server, hit Ctrl-C in the terminal window where it’s running. In development mode, Spree does not generally require you to stop the server; changes you make in files will be automatically picked up by the server.

5.2 Logging into the Backend

The next thing you’ll probably want to do is to log into the admin interface. Use your browser to navigate to http://localhost:3000/admin. You can login with the username and password you entered during the database setup step.

If you just accepted the defaults, the username is spree@example.com and the password is spree123. Otherwise, you can use a simple rake task, to create your own admin user:

$ rake spree_auth:admin:create

Upon successful authentication you should see the admin screen:

Feel free to explore some of the backend features that Spree has to offer and to verify that your installation is working properly.