Migrate from Spree
You can migrate your Spree store to Solidus. This article outlines what you need, how to migrate, and the common problems you should be aware of before making the switch.
Note that most migrations are not a one-click process. Every store is different and will have different requirements.
- Familiarity with Ruby on Rails.
- Familiarity with your Rails application and your store's database.
- A store running on Spree 2.2, 2.3, or 2.4.
- A Rails application that can readily be upgraded from 4.1.x to a newer version.
If your store uses an earlier version of Spree, consider upgrading to 2.4 before you start the migration process. If your store runs 3.0 or newer, see our note about migrating from Spree 3.0 or newer .
Remember that you should always back up your databases before attempting a migration in a production environment.
This article walks you through a basic migration from Spree 2.4 to Solidus 1.4. Note that if you have customized your Spree-based store, or you use another version of Spree, this article may not include additional migration steps that you need to perform. After you have successfully upgraded to Solidus 1.4, you can incrementally upgrade to the most recent version .
You are running a store on Spree 2.4.4. You use the standard
gem for authentication, and your application runs on Rails 4.1.x. Your
has the following lines:
gem 'spree', '~> 2.4.0' gem 'spree_auth_devise', github: 'spree/spree_auth_devise', branch: '2-4-stable' gem 'rails', '~> 4.1.0'
You want to migrate from Spree to Solidus. To make the upgrade process more straightforward, you plan to migrate to Solidus 1.4 before upgrading to Solidus 2.0 and beyond.
Replace Spree gems in your Gemfile
First, replace the Spree gems in your
Gemfile. In their place, you are going
to add Solidus gems locked to their
1.4 versions. You may want to keep the
lines from your Spree gems commented out for reference:
gem 'solidus', '~> 1.4.0' gem 'solidus_auth_devise', '~> 1.4.0' # gem 'spree', '~> 2.4.0' # gem 'spree_auth_devise', github: 'spree/spree_auth_devise', branch: '2-4-stable'
Prepare to upgrade Rails to 4.2.x
If you attempt to run
bundle update at this point, notice that Bundler runs
into a number of dependency issues. Next, you need to upgrade to Rails 4.2 for
Update the Rails version in your
gem 'rails', '~> 4.2.0'
Note that upgrading Rails affects many other gem versions in your application.
If you use Rails's default asset pipeline, for example, we recommend that you
explicitly update the versions of the
sass-rails gem in your
well as explicitly setting the versions for the dependencies
gem 'sprockets', '2.11.0' gem 'bourbon', '< 5.0.0' gem 'sass-rails', '~> 4.0.0'
Run bundle update
After you have replaced the Spree gems in your
Gemfile and prepared to upgrade
Rails to 4.2.x, you can update your application with Bundler:
At this point, the update should run successfully. If it does not, check your
Gemfile for other gems that require specific updates to their dependencies.
Install Solidus migrations
Now that you have successfully installed the Solidus gems, you need to copy all of the Solidus-specific migrations into your application:
bundle exec rake railties:install:migrations
Start the Solidus installation process
Now that your Spree store includes Solidus and its migrations, you can start the Solidus install process:
bundle exec rails generate spree:install.
bundle exec rails generate solidus:auth:install.
bundle exec rake db:migrate.
rails generate spree:install step, Rails should prompt you to
overwrite some configuration files:
/config/initializers/spree.rb: Adds additional default configuration settings for Solidus gems.
/vendor/assets/stylesheets/spree/frontend/all.css: Removes an empty line.
/vendor/assets/stylesheets/spree/backend/all.css: Removes an empty line.
You can respond to the prompt with
d to see a diff of the changes to each
rails generate spree:install step also asks if you would like to create
another admin user. However, you can safely continue using the admin user from
Manage deprecation warnings
After upgrading your Spree 2.4 application to Solidus 1.4, you may see some deprecation warnings. The amount of deprecation warnings depends on how many Spree features you use that are being deprecated in Solidus, as well as additional gems your application uses.
If you plan to upgrade to Solidus 2.0, you need to deal with the deprecated code within your application code. The warnings should give you straightforward solutions.
For deprecation warnings that come from specific gems, you may be able to get rid of them by simply upgrading those gems.
Upgrade Solidus incrementally
Now that you have transitioned from Spree to Solidus, you upgrade from Solidus 1.4 to the next major version: 2.0. From 2.0, you can upgrade to each minor version incrementally until you are at the newest version.
Upgrading incrementally is less risky than upgrading straight from 1.4 to 2.4. It ensures that you have all of the necessary migrations and don't inadvertently break existing functionality in your application code.
Use the notes in Solidus's changelog to help you upgrade to each minor version of Solidus gracefully.
Migrating from Spree 3.0 or newer
Solidus is a fork of Spree 2.4. After Spree 2.4, the Spree and Solidus code bases start to diverge. For example, Spree 3.0 introduces a Bootstrap-based frontend and backend which is significantly different from Solidus's frontend and backend.
If you run Spree 3.0 and want to migrate, we suggest that you upgrade to some intermediate versions of Solidus first:
- Upgrade to Solidus 1.4 first. This is the last version of Solidus that uses Rails 4.2.
- Upgrade from Solidus 1.4 to Solidus 2.0, which runs on Rails 5.0.
- Upgrade from Solidus 2.0 to Solidus 2.1. Solidus 2.1 removes methods that were deprecated in Solidus 1.4.
Solidus is an open source platform supported by the community. We encourage everyone using Solius to contribute back to the documentation and the code.