First-time installation

This article will help you install and run Solidus on your local machine for the first time. This guide is aimed specifically at developers running macOS.

If you run Linux or Windows, or you don't use Homebrew on your Mac, you can still follow this guide. However, you may want to consult other documentation while installing Ruby, SQLite 3, and other dependencies on your system.

Getting help

If you're following this guide and still having trouble installing Solidus, join the Solidus Slack team and start a conversation in the #support channel .

If you are still not able to get Solidus running, open an issue on GitHub with any information you think would help to reproduce the issues you're having. That would include your operating system and its version, the versions of Ruby, Rails, and SQLite 3 that you are running, and the specific error messages you are receiving during installation.

Before you start

Solidus is an ecommerce platform built with Ruby on Rails . To get the most out of Solidus, we recommend that you familiarize yourself with Ruby on Rails, as well as the Ruby programming language beforehand.

Because Solidus is a Rails engine, much of what the Rails Guide on Engines explains applies directly to Solidus, too.

We also recommend configuring your development environment so that you can install RubyGems without sudo .

System requirements

The following software is required to get Solidus running:

We recommend using Homebrew to install these dependencies on your Mac. Throughout this article, we will use the brew command for installing system dependencies. The Ruby documentation also recommends using Homebrew if you need to upgrade from your system's Ruby.

Quick start

Using Homebrew, you can install all of the requirements using the following commands:

Bash
    
      brew install ruby sqlite3 imagemagick
gem install rails

    
  

See more detailed installation information below.

Upgrade Ruby on macOS

If you run macOS Sierra or an older OS, you system's version of Ruby will need to be upgraded from 2.0.x to 2.2.2 or newer. You can check what version of Ruby you have installed with the following command:

Bash
    
      ruby --version

    
  

The Ruby documentation recommends installing another, newer instance of Ruby installing another, newer instance of Ruby using Homebrew:

Bash
    
      brew install ruby

    
  

Homebrew prioritizes the Homebrew installation of Ruby (at /usr/local/bin/ruby) above the system installation (/usr/bin/ruby).

Install SQLite 3

Rails and Solidus use SQLite 3 as the default relational database. SQLite is a widely-supported, lightweight way to send and receive data. Using Homebrew, you can install the latest version of SQLite 3 using the following command:

Bash
    
      brew install sqlite3

    
  

Alternatively, you can download the pre-compiled binary from the SQLite website .

After the installation, check that it has been installed by checking the version number:

Bash
    
      sqlite3 --version

    
  

If all is well, this command will return a version number that looks something like 3.16.0 2016-11-04 19:09:39 0f3eed3324eda2a2b8d3301e5a43dc58a3a5fd5f.

Install Rails

Rails includes everything you need to build and extend a web application. Once you have Ruby and SQLite 3 installed on your system, you can install Rails via the RubyGems gem command that comes as a part of Ruby:

Bash
    
      gem install rails

    
  

This installs Rails as well as its dependencies.

Install ImageMagick

ImageMagick helps you create, edit, and save to hundreds of image file formats. It is required to use Paperclip , which is how Solidus currently handles file attachments. To install ImageMagick via Homebrew, use the command:

Bash
    
      brew install imagemagick

    
  

Alternatively, you can download a pre-compiled binary for macOS from the ImageMagick website .

Setup and installation

Once you have installed all of the system requirements, we can start setting up Solidus.

Create and configure new Rails project

First, we need a new Rails project:

Bash
    
      rails new your_solidus_project_name

    
  

Once the new project has finished being created, we can open the project's newly created Gemfile in a text editor and add the required Solidus gems as new lines:

Ruby
    
      gem 'solidus'
gem 'solidus_auth_devise'

    
  

By requiring solidus in your Gemfile, you are actually requiring all five of the core Solidus gems:

All five of these gems are maintained in the Solidus GitHub repository . They are documented at a separate documentation site .

For a first-time installation, we recommend requiring solidus as it provides a fully-functioning online store. However, you may wish to only use a subset of the gems and create a more custom store.

Once you have saved the Gemfile, ensure you are in your Rails project directory, and then install the project's dependencies using Bundler.

Bash
    
      cd /path/to/your-solidus-project-name
bundle install

    
  

Start generating Solidus configuration files

After the gems have been successfully installed, you need to create the necessary configuration files and instructions for the database using generators provided by Solidus and Railties.

First, run the spree:install generator:

Bash
    
      bundle exec rails generate spree:install

    
  

This may take a few minutes to complete, and it requires some user confirmation.

Set the administrator username and password

The spree:install generator prompts you to configure the Solidus administrator username and password values.

The default values are as follows:

  • Username: admin@example.com
  • Password: test123

Prepare Solidus database migrations

Next, you need run the solidus:auth:install generator and install your database migrations using the following commands:

Bash
    
      bundle exec rails generate solidus:auth:install
bundle exec rake railties:install:migrations

    
  

Finally, you need to run the migrations that Railties created. This creates the e-commerce–friendly models that Solidus uses for its database:

Bash
    
      bundle exec rake db:migrate

    
  

Start the Rails server and use the sample store

Once the database migrations have been created, you should be able to successfully start the Rails server and see the sample store in your browser.

First, start the server:

Bash
    
      bundle exec rails server

    
  

Once the server has started, you can access your store from the following URLs:

You can browse the sample store's pages and mock products, and so on.

Feedback

Solidus is an open source platform supported by the community. We encourage everyone using Solius to contribute back to the documentation and the code.

If you’re interested in contributing to the docs, get started with the contributing guidelines. If you see something that needs fixing and can’t do it yourself, please send us an email.