This guide will teach what each you how to install Solidus and configure Solidus in a new or existing Rails application.
Solidus requires the following software on the host to run properly:
- Ruby interpreter: Solidus always supports the oldest maintained Ruby branch.
- Rails: Solidus always supports the oldest maintained Rails version.
- Relational database: the core and the extensions are always tested with MySQL and PostgreSQL, but other relational databases should work as well.
- libvips or ImageMagick: this is needed for manipulating product images and other assets. You need one or the other, depending on the configured variant processor.
Solidus has been designed as an ecosystem of independent libraries (gems, in the Ruby world) that work well in isolation, but collaborate to give you an amazing eCommerce experience when used together. A standard Solidus installation is composed of the following gems:
- solidus_core: provides the core data models and eCommerce business logic. This is the bare minimum for a Solidus install.
- solidus_backend: provides the standard Solidus backend, a powerful administrative UI you can use to manage your Solidus store.
- solidus_api: provides the Solidus REST API. The API is required by the backend, but you may also use it for your own purposes (e.g. for JS interactions in the storefront).
Besides, Solidus aims to be agnostic of the storefront. We provide solidus_starter_frontend as a bootstrap solution from which a tailored store can be built. Otherwise, you can create your storefront from scratch using whatever technology you prefer.
For maximum flexibility, you can decide you just want to install specific gems and build the rest of the functionality yourself. Or, if you want the full-fledged Solidus experience, you can install the solidus gem, which ties them all together and will give you a complete store. This is the approach we'll be following in this guide.
In a new app
If you don't have an existing Ruby on Rails application yet, simply create one with:
$ rails new -T amazing_store
This command will generate a new Rails application in the
amazing_store directory. This application
will be using Sqlite3 as the database adapter by default and will skip generating default test files
-T option). If you want to see all the installation options offered by Rails, run
rails new --help.
Once you have generated your new Rails application, you can proceed as if you were installing Solidus in an existing app.
In an existing app
If you have an existing Ruby on Rails application, installing Solidus is fairly simple. In your CLI:
$ bundle add solidus
$ bin/rails generate solidus:install
If you want to see all the installation options offered by Solidus, run
bin/rails generate solidus:install --help.
The installer will prompt you on a few questions before completing the installation:
- Which storefront you want to install. We provide a ready-to-use template called solidus_starter_frontend to quickly get up and running. There's also the option to choose no storefront and build your own.
- What payment service you would like to install with Solidus. Currently, it comes packaged with Paypal, Stripe and Braintree but you can also choose to start without a payment service via the "none" option and add one later. If you choose one, remember to check their READMEs for additional configuration steps.
Once the installation has completed, you can now start your Rails server:
$ bin/rails server
You should now be able to access your storefront at http://localhost:3000.
You can also access Solidus' admin UI at http://localhost:3000/admin
with the default credentials (email:
[email protected], password:
Once Solidus has been installed, you can get a feel of its configuration options by looking at the
generated initializer in
The very first line on it will be very similar to this one:
Some of the default values for Solidus preferences depend on the Solidus version. That line makes sure you use the defaults for the version you have just installed.
You'll have to bump the loaded version when you upgrade to a new Solidus version.
Right after that, you'll see a block for the preferences that apply to the core component:
Spree.config do |config|
config.currency = "USD"
Take a look at
class for all the available settings. You can adjust some of them now, but you will probably want to
revisit them as you develop your store and customize Solidus to fit your needs.
Finally, the initializer contains a block for all the other components you have installed. For instance:
Spree::Api::Config.configure do |config|
config.requires_authentication = true
You can inspect the current values for the settings running
Spree::Config for core
Spree::Api::Config for the backend and API components,
respectively, in the console.