This article was peer reviewed by Thom Parkin. Thanks to all of SitePoint’s peer reviewers for making SitePoint content the best it can be!
Solidus is an open source, eCommerce application for high volume retailers. Built with Ruby on Rails, this mountable engine provides a scalable, stable, and highly customizable platform for online commerce. It’s just a continuation (meaning, a fork) of Spree 2.4 without the commercial direction of the newly-acquired Spree Commerce
In this tutorial, we will learn to install Solidus.
NOTE: I am using Ubuntu 14.04 as I write this tutorial. For the sake of readers using Mac, links are added where necessary.
We will be using PostregSQL as our default database, it is important we have it installed.
For Mac users, follow these instructions here.
For Ubuntu users, in your terminal enter:
sudo apt-get update
Enter your admin password when prompted. Next, we’ll install PostgreSQL with the following command:
sudo apt-get install postgresql postgresql-contrib
This installs the core PostgresSQL engine and the additional packages that work with the database server.
Now we’ll create a user, for the purpose of this tutorial the user will have same name as our store:
sudo -u postgres createuser sprubyshop -s sudo -u postgres psql
At the postgresql prompt, enter:
Then enter your password (You’ll be required to enter it twice.) You can now exit using
CTRL + D.
Generating Rails App
Open up your terminal and install the rails gem, if you do not have it installed yet:
gem install rails
That should install the latest available version of Rails gem. We can now generate our Rails application. From your terminal run:
rails new sprubyshop -d postgresql
Here we ask rails to generate an app called “sprubystore”, setting the default database to PostgreSQL. This adds the
pg gem into our Gemfile and sets it as the default database. It also means
sqlite3 won’t be in our Gemfile. We’re using PostgreSQL for development, test, and production environments. This is why we went through the stress of installing Postgres on our machine earlier.
With that, our store application should be generated. Open your Gemfile and you should see the
pg gem there. If the
sqlite3 gem happens to still be there, comment it out. Your Gemfile should look like this:
source 'https://rubygems.org' gem 'rails', '4.2.3' gem 'pg' gem 'sass-rails', '~> 5.0' gem 'uglifier', '>= 1.3.0' gem 'coffee-rails', '~> 4.1.0' gem 'jquery-rails' gem 'turbolinks' gem 'jbuilder', '~> 2.0' gem 'sdoc', '~> 0.4.0', group: :doc group :development, :test do gem 'byebug' gem 'web-console', '~> 2.0' gem 'spring' end
Next, we need to edit the database configuration. Navigate to config/database.yml, using your text editor, and change the
development options to look like what I have below:
test: <<: *default host: localhost database: sprubyshop_test username: sprubyshop password: sprubyshop development: <<: *default host: localhost database: sprubyshop_development username: sprubyshop password: sprubyshop
To create the database, open up your terminal and run:
therubytracer to your
Gemfile or install NodeJS. For the purpose of this tutorial we would defer to using NodeJS which you can install like so:
sudo apt-get install nodejs
On the Mac, use homebrew (
brew install nodejs)
Now try running the
rake command and it should work, without error.
Imagemagick is needed for Solidus to work. You need it to take take care of product thumbnail generation. Let’s install that:
For Mac users;
brew install imagemagick
For Ubuntu users;
sudo apt-get install imagemagick
Now it’s time to install the solidus gem. Open up your Gemfile and add the following:
gem 'solidus' gem 'solidus_auth_devise
As you can see, we’re going to use Devise for authentication.
bundle install to install the gems.
After installing the gems, you’ll have to run the generators to create necessary the configuration files and migrations.
bundle exec rails g spree:install
During installation, you’ll be asked to create an Admin user:
Create the admin user (press enter for defaults). Email [email@example.com]: Password [spree123]:
For now just use the default options.
You might have noticed a warning during installation:
[WARNING] You are not setting Devise.secret_key within your application! You must set this in config/initializers/devise.rb. Here's an example: Devise.secret_key = "b2e58acf575db38200dd2058ecd85539c8713c9f1efd45ad42c68c593c6cd4cb78e0d4388ce84672879c359212dedb4b73f3"
Fixing this is easy, enter the command below in your terminal:
rails g solidus:auth:install
The warning will pop up one more time, afterwhich a config file for devise will be created.
Excellent! Now it’s time to check our progress. Start up your rails server using:
Open your browser and point to
http://localhost:3000 to see what we have.
To view the admin dashboard, point your browser to
Let us see how the admin dashboard looks like. Login with the default details that Solidus provided you with during installation.
Email: firstname.lastname@example.org Password: spree123
Solidus presents you with all the basic requirements for an e-commerce store and more. There is the “Orders” section that handles all the orders from your customers. The “Product” panel makes management of products easy with a couple of clicks. You are also able to generate reports from the “Reports” panel. All these options are visible on the right side of the admin dashboard.
There is a guide available to walk you through these options.
Add New User
We do not want to use the default login account. Solidus gives us an easy way of adding accounts in just a few steps:
From inside the Admin panel, click on Users at the right hand side of your screen. You’ll be presented with a screen that shows you the current user, which, at the moment, is the default user.
Click on the New User at the right side of your screen.
Fill the form as you please and click CREATE.
Now logout from the Spree default account and login with the details you just created. To delete the default Solidus account, from the Users panel click on Users List. You’ll see all the available Users listed there. Click on the trash icon to delete a User.
Replacing the Solidus Default Logo
Solidus comes with a default logo which you can see at the top left corner of your store. This logo is available both for the main and adminstrator views of the store. Let us see how we can change that.
Copy your logo, from your store home folder migrate to
app > assets > images using a file explorer. Create a folder named
logo and paste your custom logo in there.
Just doing that won’t make the logo change, we have to specify it inside of our config file. Open up text editor to config/initializers/spree.rb.
Change the line below:
#config.logo = "logo/solidus_logo.png"#
Let it look like this:
config.logo = "logo/sprubyshop_logo.png"
Restart the Rails server for the logo to change. We do not have to specify a path for the logo as the assets folder where we pasted the logo is the default path.
The administrator logo is modified similarly. To change it, edit the line below in spree.rb:
config.admin_interface_logo = "logo/solidus_logo.png
To look like this:
config.admin_interface_logo = "logo/sprubyshop_logo.png"
NOTE: The name of my logo is sprubyshop_logo.png
Your spree.rb should look like this:
# Configure Solidus Preferences # See http://docs.solidus.io/Spree/AppConfiguration.html for details Spree.config do |config| # Without this preferences are loaded and persisted to the database. This # changes them to be stored in memory. # This will be the default in a future version. config.use_static_preferences! # Core: # Default currency for new sites config.currency = "USD" # from address for transactional emails config.mails_from = "email@example.com" # Uncomment to stop tracking inventory levels in the application # config.track_inventory_levels = false # When true, product caches are only invalidated when they come in or out of # stock. Default is to invalidate cache on any inventory changes. # config.binary_inventory_cache = true # Frontend: # Custom logo for the frontend config.logo = "logo/sprubyshop.png" # Template to use when rendering layout # config.layout = "spree/layouts/spree_application" # Admin: # Custom logo for the admin config.admin_interface_logo = "logo/sprubyshop.png" # Gateway credentials can be configured statically here and referenced from # the admin. They can also be fully configured from the admin. # # config.static_model_preferences.add( # Spree::Gateway::StripeGateway, # 'stripe_env_credentials', # secret_key: ENV['STRIPE_SECRET_KEY'], # publishable_key: ENV['STRIPE_PUBLISHABLE_KEY'], # server: Rails.env.production? ? 'production' : 'test', # test: !Rails.env.production? # ) end Spree.user_class = "Spree::LegacyUser"
Here is how mine looks like:
Solidus actually consists of several different gems, each of which is maintained in a single repository and documented in a single set of online documentation. By requiring the solidus gem you automatically require all of the necessary gem dependencies which are:
- solidus_api (RESTful API)
- solidus_frontend (Cart and storefront)
- solidus_backend (Admin area)
- solidus_core (Essential models, mailers, and classes)
- solidus_sample (Sample Data)
All the gems are designed to work together to provide a fully functional e-commerce platform. You can learn more about this on Solidus Github Repository.
In this tutorial, we learned how to install Solidus, add a new user, and add a custom logo. I hope to cover more customization in a future post or two.
Thanks for staying with me. Feedback is always welcome.