Skip to main content
Version: 4.0

Installing Solidus

This guide will teach what each you how to install Solidus and configure Solidus in a new or existing Rails application.

System requirements​

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.

Library architecture​

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. standard Solidus storefront along with helpers to build your own.
  • 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.

Installation steps​

In a new app​

If you don't have an existing Ruby on Rails application yet, simply create one with Sqlite3 as your database:

$ rails new amazing_store

Solidus doesn't require the JavaScript compiler shipped with Rails by default (Webpacker). You are still free to install it and use it in your store, though.

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'
# Add `--help` to learn about all available options
$ bin/rails generate solidus:install

The installer will prompt you on a few questions before completing the installation:

  • It will ask if you would like to use the default authentication solution, Devise, or implement your own.
  • It will also prompt you to choose which storefront you want to install. We recommend picking solidus_starter_frontend to quickly get up & running. You might need to choose the deprecated solidus_frontend if you want to use an extension that still relies on it. There's also the option to choose no frontend.
  • Next, it will ask what payment service you would like to install with Solidus. Currently, it comes packaged with Paypal and Bolt as the two default options.

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: test123).

First-time configuration​

Once Solidus has been installed, you can get a feel of its configuration options by looking at the generated initializer in config/initializers/spree.rb.

The very first line on it will be very similar to this one:

Spree.load_defaults '3.2'

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.

info

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"
  # ...
end

Take a look at the Spree::AppConfiguration 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
end

Just like for the core, see Spree::ApiConfiguration and Spree::BackendConfiguration for the complete list of settings.

info

You can inspect the current values for the settings running Spree::Config for core and Spree::Backend::Config or Spree::Api::Config for the backend and API components, respectively, in the console.