Running the Source

Gem Requirements

You must make sure that you have all of the required gems installed first.

gem install has_many_polymorphs
gem install highline
gem install mini_magick

Multiple Modes

Instance Mode

You can run Spree directly from the git repository that you clone from Github. This does not require installation of the Spree gem. Its also probably the best way to experiment with the source code. Spree contributors will also find themselves working in this mode frequently.

Steps

1. Create config/database.yml

This configuration is intentionally omitted from the source repository. Do not ever commit this to your Github fork since it causes problems when contributing your changes back to the main Spree project.

2. Generate the database

cd foo
rake db:bootstrap

If something goes wrong during this step you most likely are missing a required gem. Use the rake gems to list the required gems and rake gem:install to install them.

3. Start the server

script/server

Gem mode

Spree is intended to be used to jump start a new commerce application. Once you install the gem you can do

spree foo

When you use Spree this way, you create a new application with the following directory structure

foo
foo/config
foo/db
foo/log
foo/public
foo/script
foo/vendor

This is essentially a Rails application minus the app directory. The application you built can be run using script/console. This is how you should create your real world Spree app once you are done experimenting with the source. It will allow you to upgrade to future versions of Spree with less aggravation. If you want to override the default behavior of Spree there are always Extensions.

Vendor mode

You may wish to experiment with the Spree source code while trying out some custom extensions or making other adjustments specific to your store. That is where “vendor mode” comes into play.

If you place a copy of the Spree source in the vendor/spree directory, then Spree will load from this location instead of the gem. It is important that you distinguish between #{SPREE_ROOT}/vendor and #{RAILS_ROOT}/vendor (see the FAQ if you are unclear on this difference.)

You can also create a symlink inside #{RAILS_ROOT}/vendor and point it to your local git repository containing the Spree source. This way you can build your store and/or extensions and test them with the latest and greatest source code.

When it comes time to deploy your Spree-based application you can freeze the latest version of the Spree gem (just like you can do with Rails.)

rake spree:freeze:gems

This will unpack the Spree gem into #{RAILS_ROOT}/vendor/spree. Your new application will then effectively be running in “vendor mode.” When it comes time to upgrade you can unfreeze and freeze a new copy, etc.