More at spreecommerce.com: Features | Support | Blog | Demo | Community | Download

Getting Started With Spree

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

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.

gem 'spree', '0.30.0.beta1'

4.3 Installing the Dependencies

Now its time to install any new gem dependencies we have created. For instance, if you do not already have the appropriate Spree gem or database driver, bundler will install it for you.

$ bundle install

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.

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:

rails g spree:site rake spree:install

If you have an existing Rails application with customizations (as opposed to just the starter app that we’ve shown here) you will want to make a note of any files that this task changes. Its possible that it may alter your javascript or stylesheet files in undesirable ways. You should check the differences via git diff or some other process and manually merge the needed changes if necessary.

Spree also comes with sample data (products, orders, etc.) If you’d like to install the migrations and assets associated with the sample data then you can run this additional rake task.

rake spree_sample:install

4.6 Populating the Database

Now that you have your database configured, it’s time to have Spree populate it with the necessary tables and data. You can do this by running a rake command:

$ rake db:bootstrap

This will effectively drop the existing database and recreate it from scratch with the option of creating sample product data. It is disabled for production databases for safety reasons. For a production database you should use rake db:migrate to create the tables and rake db:admin:create to create the admin user.

You can also migrate the database in the more “traditional” rails manner using more familiar rake tasks. The following series of commands is equivalent to running the bootstrap task described above:

rake db:migrate rake db:seed rake db:sample rake db:admin:create

If you skip the sample and admin create tasks there will be no admin user. In this situation the first user you create in Spree will be given the admin role automatically.

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:

Spree welcome screenshot

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 inteface. User your browser window to navigate to http://localhost:3000/admin. You can login with the username and password you entering during the database setup step. If you just accepted the defaults, the username is spree@example.com and the password is spree.

Upon successful authentication you should see the admin screen:

Admin welcome screenshot

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