Solidus: a Rails eCommerce framework you fork and own

The problem Solidus solves, and who feels it

Hosted commerce platforms decide what you can change. When a pricing rule, a tax edge case or a fulfilment flow does not fit the platform's model, you work around it, and the workaround becomes permanent. Solidus takes the opposite position: the store is a Rails application you deploy, and the commerce logic is Ruby you can edit.

The README describes it as a complete open source e-commerce solution built with Ruby on Rails, and notes it is a fork of Spree. That lineage matters. Solidus exists because a group of Spree users wanted a project governed differently, and the repository shows the result: GOVERNANCE.md at the top level, a community guidelines page on the guides site, and Open Collective funding tiers for backers, bronze, silver and gold partners. Nebulab is named as the main code contributor and director.

The audience is narrow and specific. You are a Ruby shop, or you are willing to become one. You have a checkout that behaves unlike anyone else's, or a product catalogue with rules that no admin UI expresses. If your store is a standard cart with standard shipping, the cost of owning a Rails deployment is hard to justify against a hosted option.

Four gems, one application, and what that buys you

Requiring the solidus gem in a Gemfile pulls in four gems, and the split is the architecture. solidus_core holds the essential models, mailers and classes. solidus_backend is the admin area. solidus_api is the RESTful API. solidus_sample provides sample data. Bundler installs all four together.

The README is explicit that this is a default, not a requirement: you may use only solidus_core and combine it with your own custom frontend, admin interface and API. That is the most consequential design decision in the project. A team that has already built a storefront in something other than Rails views, or an admin in something other than the bundled backend, can take the order, product and payment models and leave the rest. The cost is that you then own the parts you dropped, including the API surface your mobile client or integration partner depends on.

The repository layout confirms the split. The top level carries admin/, api/, backend/, core/, promotions/, legacy_promotions/, sample/, storefront/ and i18n/ as separate directories, alongside a Rakefile, a solidus.gemspec and a docker-compose.yml. Each of those is a gem boundary, which means each is also a versioning boundary: upgrading the admin and upgrading the core are separate decisions with separate changelogs.

Installing Solidus and getting a store on localhost

The README says to begin by making sure ImageMagick is installed, because Paperclip requires it, and points at the download page or Homebrew on a Mac. Then it directs you to storefront/README.md for the full installation with the current storefront, so the exact generator invocation lives there rather than in the root README.

The installation generator is solidus:install, and by default it runs migrations and adds seed and sample data. That default is worth pausing on. A first install that seeds sample products, orders and users gives you something to click through immediately, and it also puts data in your database that you must remove before production. The README documents how to turn each part off:

bin/rails g solidus:install --migrate=false --sample=false --seed=false

If you skip those steps, the README gives the commands to run them later. Migrations first, then the schema, then seed data, then the sample loader, which is a separate rake task named spree_sample:load:

bin/rails railties:install:migrations
bin/rails db:migrate
bin/rails db:seed
bin/rails spree_sample:load

Start the server with bin/rails s. The storefront answers at http://localhost:3000/ and the admin at http://localhost:3000/admin/. During installation you are asked for an admin email and password; the README states the default values are [email protected] and test123. Change that pair before anything is reachable from a network.

If you prefer a container, the repository's docker-compose.yml defines an app service built from .dockerdev, with mysql 8.0 and postgres 13.2 services behind it. The app service maps port 3000 by default, controlled by SANDBOX_PORT, and sets DB_USERNAME and DB_PASSWORD to root and password. Its command runs bundle check or bundle and then holds the container open, printing that the container is initialized and to see README.md for further steps. That is a development environment, not a production topology.

Where Solidus is the wrong tool

The README carries a warning that deserves to be read twice: the master branch is not guaranteed to ever be in a fully functioning state, and it is too risky to use in production. The gem line it offers for the bleeding edge, gem 'solidus', github: 'solidusio/solidus', is therefore a development convenience only. If your team's instinct is to track main, Solidus will punish it.

Development mode is another trap the README acknowledges directly. It notes that a Solidus store may run slowly in development because each CSS and JavaScript asset is loaded separately. That is normal Rails asset behaviour, and it means local performance tells you nothing about production performance. Do not size infrastructure from what you see on localhost.

The larger limitation is operational. Solidus is a framework, not a service. There is no vendor to page when checkout breaks at 2am. The README routes questions to a Slack #support channel and a security mailing list, which are community channels, not an SLA. A team without Ruby on call, or without the budget to hire it, is taking on risk that a hosted platform would absorb.

Finally, the gem split cuts both ways. If you take solidus_core alone, you inherit the upgrade obligation for every dependent gem you did not take, because the storefront and admin you wrote must keep pace with core changes yourself.

Solidus against Spree, and against writing it yourself

The obvious alternative is Spree, and the README names it as the project Solidus forked from. The difference is not feature set, it is governance and release cadence. Solidus is steered by Nebulab as main contributor and director, with a published governance document and Open Collective funding, and it publishes versioned releases: v4.7.0 in April 2026, then v4.7.1 and v4.6.3 both in September 2026. The maintenance line on the older 4.6 series is the detail to notice, because it means a team on 4.6 is not stranded when 4.7 lands. Anyone choosing between the two should compare the release history and the governance documents of each, not the feature lists, because the features converge and the decision-making does not.

The other alternative is building commerce into a Rails app yourself. Solidus wins on the parts nobody enjoys writing: order state machines, payment and refund flows, promotions, tax and shipment models, an admin, and a REST API. It loses on the parts you would have written exactly the way you wanted. The honest test is whether your differentiation lives in the models Solidus already provides. If it does, you are paying for someone else's opinions. If it lives above them, in a custom frontend, a custom admin or a custom API, the README's solidus_core-only path is the one that matches your problem.

Maintenance, upgrades and the licence

The repository is not archived, and the last push was on 2026-09-22, so the codebase is being worked on now. The release pattern is what a team should plan against: a minor release in April 2026, followed by patch releases in September 2026 on both the 4.7 and 4.6 lines. That backporting to the previous minor is the practical support window. Budget an upgrade every time a minor lands, and expect the work to be migrations plus whatever your extensions override.

The upgrade cost is concentrated in the extension points. Solidus is designed to be customized, and customization is what makes the next upgrade expensive. A store that only configures Solidus upgrades cheaply. A store that decorates core models, replaces the checkout state machine and overrides admin controllers pays for each of those decisions a second time at upgrade. The repository's own layout reflects this tension: promotions/ and legacy_promotions/ exist side by side, which is what happens when a subsystem is replaced and the old one is kept for compatibility.

On licensing, the project is BSD-3-Clause. That is a permissive licence, which generally means you can use it in a commercial product, modify it and redistribute it, provided the copyright notice and licence text are retained. It does not come with a warranty. This is not legal advice, and if your organisation has specific obligations around attribution or redistribution, have counsel read the LICENSE file rather than this paragraph.

Editorial conclusion

Adopt Solidus if you have Ruby engineers who want to modify checkout, pricing and fulfilment logic in a codebase they control, and you accept that upgrades are gem and migration work on your schedule. Do not adopt it if you need a hosted cart with a support contract and no deployment surface. Before committing, verify three things: that your Ruby and Rails versions satisfy the Gemfile, that ImageMagick is installed for Paperclip, and that the solidus:install generator flags match the data you actually want seeded.

Frequently asked questions

Official sources

1. License: BSD-3-Clause
2. Project website
3. README
4. Releases
5. solidusio/solidus on GitHub