Skip to main content
Version: Next

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.
  • 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:

$ rails new -T amazing_store
info

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 (via the -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
info

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: 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 '4.4'

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.