Skip to main content
This guide is aimed at advanced users who want to add Spree to an existing Rails application. If you are new to Spree, please follow the Quickstart guide.

​
Overview

If you already have a Ruby on Rails application, you can add Spree to it by following these steps.
Spree works with PostgreSQL, MySQL, and SQLite — whatever database your Rails app already uses. No database migration is needed.

​
1. Add Spree gems

Add these lines to your project Gemfile: 
spree_opts = { 'github': 'spree/spree', 'branch': 'main' }
gem 'spree', spree_opts # core, API, and CLI
gem 'spree_admin', spree_opts # Admin panel (optional)
gem 'spree_storefront', spree_opts # Storefront (optional)
gem 'spree_emails', spree_opts # transactional emails (optional)
gem 'spree_sample', spree_opts # dummy data like products, taxons, etc (optional)
And run the following command to install the gems: 
bundle install

​
2. Run the install generators

Spree uses a modular installation approach. First install the core, then add optional components.

​
Install core Spree

This installs core models, API, CLI, and authentication: 
bin/rails g spree:install --user_class=Spree::User --authentication=devise
Core installation options:
OptionDescription
user_classThe class for your users, eg. Spree::User or User
admin_user_classThe class for admin users (defaults to user_class)
authenticationAuthentication gem: devise or custom
migrateWhether to run migrations (default: true)
seedWhether to run the seed file (default: true)
sampleWhether to add sample data (default: false)
admin_emailEmail of the first admin user
admin_passwordPassword of the first admin user

​
Install Admin Panel (optional)

bin/rails g spree:admin:install
bin/rails g spree:admin:devise  # if using Devise authentication

​
Install Storefront (optional)

bin/rails g spree:storefront:install
bin/rails g spree:storefront:devise  # if using Devise authentication

​
3. Add sample data (optional)

To add sample data to your store, run: 
bin/rake spree_sample:load
This will add some products, categories, and will setup a checkout flow to your store.

​
4. Exploring Your Store

Feel free to explore your store. You can do so because Spree comes with a default pre-built Storefront and Admin Panel.

​
Logging into the Admin Dashboard

Use your browser window to navigate to http://localhost:3000/admin. You can log in with the default credentials:
  • login: spree@example.com
  • password: spree123
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.

​
Browsing Storefront

Spree comes with a default pre-built Storefront. You can access it by navigating to http://localhost:3000. You can later customize this Storefront or choose another one if you prefer Next.js or Vue.js.

​
All Done!

Congrats! You’ve set up your Spree Commerce and it’s looking amazing! Need support or want to give some feedback? You can join our community or drop us an email at hello@spreecommerce.org.