Guides

Getting Started With Spree

This guide covers getting up and running with Spree. After reading it, you should be familiar with:

  • Installing Spree, creating a new Spree application, and connecting your application to a database
  • The general layout of a Spree application
  • The basic principles behind the Spree design
  • How to quickly generate the starting pieces of a Spree application.
  • How to continue with this towards a first production system.

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:

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:

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

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 then 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. These solutions seemed to be unsatisfactory when presented with even the simplest of use cases. 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 that people do business for us to model them all specifically. Rather then come up short (like so many projects before it), Spree’s approach is to simply accept this and not even try. Instead Spree tries to focus on solving the 90% portion 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 also have very specific shipping and taxation rules. Spree needs to be flexible enough to accommodate most situations. Sensible defaults should be provided with the 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 Installation

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

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 Spree

Spree is distributed as a Rubygem. The Spree gem itself is actually very small and it depends on several other so-called “core gems.”

[TODO: Add note with link to section describing organization of source code, etc.]

If you are following the recommended approach of using bundler there really isn’t anything to install since bundler will handle all of this for you. If you wish, however, you can install Spree manually just like any other gem using the following command:

$ gem install spree

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

If you would like to skip the ImageMagick installation you can get by without it as long as you do not try to add any product images to your store. You will also have to skip the creation of the sample products (and related images.) This means you cannot run rake db:bootstrap or rake db:sample since those rake tasks require the library.

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.

In versions prior to Spree 0.30.0 you could not simply add Spree to an existing Rails application. You needed to use a special spree command to setup your project. This command customized/hacked some of the standard Rails initializers but this approach is no longer necessary due to improvements to Rails that were designed to support frameworks such as Spree.

[TODO: Possible note and link to source section detailing the Rails Engines aspect]

4.1 Creating the Rails Application

Lets 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 - its 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 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 Rails 3.0 or greater and assuming there is no conflict in model names, etc.)

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

$ cd mystore

Edit the Gemfile in your Rails application by adding the following:

$ gem 'spree'

This will used the latest stable release of Spree. If you want to require a specific version (for example a “release candidate” or “beta release”) then just specify the version as well.

4.3 Installing the Dependencies

The dependencies should be specified in a specific order. Always specify spree, followed by spree-extensions at the very end of Gemfile. For example, a tabula rasa Spree dependency list would be specified in this order: mysql2, spree, spree-paypal-express. See below for an example Gemfile with the correct order.

4.4 Configuring the Database

Just about every Rails application will interact with a database. The database to use is specified in a configuration file, config/database.yml. The file contains sections for three different environments in which Rails can run by default:

  • The development environment is used on your development computer as you interact manually with the application
  • The test environment is used to run automated tests
  • The production environment is used when you deploy your application for the world to use.

You may also want to consider creating a staging environment for your application. See the Rails documentation for help in creating additional environments.

4.4.1 Configuring a SQLite Database

Rails comes with built-in support for SQLite, which is a lightweight serverless database application. While a busy production environment may overload SQLite, it works well for development and testing. Rails defaults to using a SQLite database when creating a new project, but you can always change it later.

Here’s the section of the default configuration file with connection information for the development environment:

development:
adapter: sqlite3
database: db/development.sqlite3
pool: 5
timeout: 5000
4.4.2 Configuring Other Databases

The existing rails documentation provides detailed information on setting up all of the major databases. Please consult this documentation as Spree does not have any special requirements beyond what a standard Rails application requires.

When using a database such as PostgreSQL, you will need to create your database before you run any rails generators. Once you’ve configured your database.yml file, run the following command:

Now we have an array controller with no content. Let's add:

in apps/todos/todos.js
development:
adapter: sqlite3
database: db/development.sqlite3
pool: 5
timeout: 5000

4.5 Installing the Migrations and Other Assets

Spree is actually what is known as a Rails Engine. As of Rails 3.0 Rails Engines do not automatically copy their migrations or public assets into your Rails application. Once you’ve added the Spree gem to the Gemfile you can accomplish this by running the following command:

This project is maintained by a core team of developers and is freely available for commercial use under the terms of the New BSD License.