Before starting this tutorial, make sure you have Ruby and RubyGems installed on your system. This is fairly straightforward, but differs depending on which operating system you use.
By following this tutorial, you will create a simple Spree project called
my_store. Before you can start building the application, you need to make sure that you have Rails itself installed.
To run Spree 4.0 you need the latest Rails version, 6.0.0.
In most cases, the easiest way to install Rails is to take advantage of RubyGems:
gem install rails -v 6.0.0
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’s used within Rails before attempting to install Spree. You can install Bundler using the following command:
gem install bundler
Spree also uses the ImageMagick library for manipulating images. Using this library allows for automatic resizing of product images and the creation of product image thumbnails. ImageMagick 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 are using macOS, a recommended approach is to install ImageMagick using Homebrew. This can be done with the following command:
brew install imagemagick
If you are using Unix or Windows check out Imagemagick.org for more detailed instructions on how to setup ImageMagick for your particular system.
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.
Let’s start by creating a standard Rails application using the following command:
rails new my_store
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:
Add Spree gems to your Gemfile:
gem 'spree', '~> 4.1' gem 'spree_auth_devise', '~> 4.1' gem 'spree_gateway', '~> 3.7'
Note: if you run into
Bundler could not find compatible versions for gem "sprockets": error message, please run
Use the install generators to set up Spree:
rails g spree:install --user_class=Spree::User rails g spree:auth:install rails g spree_gateway:install
You now have a functional Spree application after running only a few commands! To see it, you need to start a web server on your development machine. You can do this by running another command:
bundle exec rails s
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.
The next thing you’ll probably want to do is to log into the admin interface.
Use your browser window to navigate to
http://localhost:3000/admin. You can login with
[email protected] and password
If you selected not to use the
--auto-accept option when you added Spree to your Rails app, and did not install the seed data, the admin user will not yet exist in your database. You can run a simple rake task to create a new admin user.
bundle exec rake spree_auth:admin:create
Upon successful authentication, you should see the admin screen:
Feel free to explore some of the Admin Panel features that Spree has to offer and to verify that your installation is working properly.
If you’ve followed the steps described in this tutorial, you should now have a fully functional Spree application up and running.
We recommend you should continue to Customization section to learn how to modify and extend your Spree application.
To learn more about Spree internals please refer Core section.