# Solidus

> Fork of Spree with enhanced features.

- Category: E-Commerce & Business
- Difficulty: intermediate
- Components: solidus, postgres
- Tags: solidus, ruby, rails, ecommerce
- Source: https://docker.recipes/ecommerce/solidus

## Overview

Solidus is an open-source, Ruby on Rails-based ecommerce platform that emerged as a community-driven fork of Spree Commerce in 2015. Built with extensibility and stability as core principles, Solidus provides a flexible foundation for building custom online stores while maintaining backward compatibility and offering enhanced features over its predecessor. The platform emphasizes clean architecture, comprehensive APIs, and a modular extension system that allows developers to customize functionality without modifying core code.

This Docker stack combines Solidus with PostgreSQL to create a robust ecommerce environment that leverages PostgreSQL's advanced relational capabilities for handling complex product catalogs, inventory management, order processing, and customer data. PostgreSQL's ACID compliance ensures data integrity for critical ecommerce operations like payment processing and inventory updates, while its JSON support enables flexible product attribute storage and search functionality that modern online stores require.

This configuration is ideal for Ruby developers building sophisticated ecommerce platforms, agencies creating custom online stores for clients, and businesses migrating from Spree who need enhanced customization capabilities. The combination provides the stability required for production ecommerce environments while maintaining the flexibility to implement complex business logic, multi-tenant architectures, and custom integrations with payment gateways, shipping providers, and third-party services.

## Features

- Multi-store support with shared product catalogs and independent configurations per store
- Comprehensive order state machine with customizable fulfillment and return workflows
- Flexible product variant system supporting unlimited option types and complex pricing rules
- Built-in promotion engine with coupon codes, bulk discounts, and rule-based pricing
- Extensible payment gateway architecture with Stripe, Braintree, and PayPal integrations
- Advanced inventory tracking with stock locations, backorders, and automated reorder points
- RESTful API with GraphQL support for headless commerce implementations
- PostgreSQL's full-text search capabilities for product discovery and filtering

## Use cases

- Fashion retailers requiring complex product variants with size, color, and style combinations
- B2B marketplaces needing role-based pricing, bulk ordering, and customer-specific catalogs
- Multi-brand retailers operating separate storefronts with shared inventory management
- Subscription commerce businesses requiring recurring billing and subscription management
- International ecommerce sites needing multi-currency support and localized tax calculations
- Digital product stores selling downloadable content with license management
- Marketplace platforms connecting multiple vendors with commission tracking and payout systems

## Prerequisites

- Docker and Docker Compose installed with at least 2GB available RAM for PostgreSQL operations
- Ruby on Rails knowledge for customizing Solidus functionality and creating extensions
- Understanding of PostgreSQL administration for database optimization and maintenance
- Port 3000 available for Solidus storefront and admin interface access
- SSL certificate and reverse proxy configuration for production deployments
- Payment gateway accounts (Stripe, PayPal, etc.) for processing customer transactions

## docker-compose.yml

```yaml
services:
  solidus:
    image: solidusio/solidus:latest
    container_name: solidus
    restart: unless-stopped
    environment:
      DATABASE_URL: postgres://${DB_USER}:${DB_PASSWORD}@postgres:5432/${DB_NAME}
      SECRET_KEY_BASE: ${SECRET_KEY}
      RAILS_ENV: production
    volumes:
      - solidus_data:/app/public
    ports:
      - "3000:3000"
    depends_on:
      - postgres
    networks:
      - solidus

  postgres:
    image: postgres:16-alpine
    container_name: solidus-postgres
    environment:
      POSTGRES_DB: ${DB_NAME}
      POSTGRES_USER: ${DB_USER}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - solidus

volumes:
  solidus_data:
  postgres_data:

networks:
  solidus:
    driver: bridge
```

## .env

```bash
DB_NAME=solidus
DB_USER=solidus
DB_PASSWORD=changeme
SECRET_KEY=your-secret-key
```

## Usage notes

- Docs: https://solidus.io/developers/
- Access storefront at http://localhost:3000, admin at /admin
- Fork of Spree with focus on stability and customization
- Ruby on Rails based - extensible via Solidus extensions
- Default admin: admin@example.com / test123
- Payment gateway integrations: Stripe, Braintree, PayPal, etc.

## Troubleshooting

- Solidus container fails with 'database does not exist': Ensure PostgreSQL container starts first and DATABASE_URL environment variable matches database credentials
- Admin login fails with invalid credentials: Use default admin@example.com/test123 or create new admin user via Rails console in container
- Asset precompilation errors in production: Verify SECRET_KEY_BASE is set and run 'rails assets:precompile' in Solidus container
- Payment gateway integration not working: Check that payment method extensions are installed and gateway credentials are configured in admin panel
- PostgreSQL connection errors after restart: Verify postgres_data volume persists and database user has correct permissions for the specified database
- Solidus extensions not loading: Ensure extensions are added to Gemfile and bundle install is run when building custom Solidus image

