Getting Started
Prerequisites
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.
Installing Rails
In most cases, the easiest way to install Rails is to take advantage of RubyGems:
gem install rails
Installing Image Magick
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.
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.
Creating the Rails Application
Let’s start by creating a standard Rails application using the following command:
rails new my_store
Adding Spree to Your 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 my_store
Add Spree gems to your Gemfile:
gem 'spree', '~> 4.1'
gem 'spree_auth_devise', '~> 4.1'
gem 'spree_gateway', '~> 3.7'
Run bundle install
Note: if you run into Bundler could not find compatible versions for gem "sprockets":
error message, please run
bundle update
Use the install generators to set up Spree:
bundle exec rails g spree:install --user_class=Spree::User
bundle exec rails g spree:auth:install
bundle exec rails g spree_gateway:install
Hello, Spree!
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.
Logging Into the Admin Panel
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
the username spree@example.com
and password spree123
.
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.
Wrapping Up
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.