Spree Commerce (Ruby on Rails) Installation and Setup

Installing and Configuring Spree Commerce (Ruby on Rails)

Spree installs into an existing or new Rails application as an Engine. The process is standard, but requires attention to version compatibility: Spree 4.x works on Rails 7.0/7.1, Spree 5.x (beta) — on Rails 7.2+. Gemfile compatibility errors are a typical issue during installation.

System Requirements

• Ruby 3.1+ (3.2 LTS recommended)
• Rails 7.0/7.1
• PostgreSQL 13+ (recommended; SQLite for development only)
• Redis 6+ (Sidekiq, caching)
• Node.js 18+ (for Sprockets/importmap or legacy Webpacker)
• ImageMagick or libvips (image processing via ActiveStorage)

Creating a New Rails Application

gem install rails -v "~> 7.1"
rails new my_shop \
  --database=postgresql \
  --skip-test \
  --skip-action-cable \
  -T

cd my_shop

Gemfile

# Gemfile
source "https://rubygems.org"
ruby "3.2.0"

gem "rails", "~> 7.1.0"
gem "pg", "~> 1.1"
gem "puma", ">= 5.0"

# Spree core
gem "spree", "~> 4.10"
gem "spree_auth_devise", "~> 4.6"
gem "spree_backend", "~> 4.10"   # Admin UI

# Payment gateways
gem "spree_gateway", "~> 3.10"

# Backgrounds
gem "sidekiq", "~> 7.0"
gem "redis", "~> 5.0"

# Assets
gem "sprockets-rails"
gem "sassc-rails"
gem "uglifier"

# Prod
gem "bootsnap", require: false
gem "image_processing", "~> 1.2"

group :development, :test do
  gem "debug"
  gem "factory_bot_rails"
  gem "rspec-rails"
end

bundle install

Spree Generators

# Install Spree Core
bin/rails g spree:install --user_class=Spree::User

# Install authentication
bin/rails g spree:auth:install

# Install Admin UI
bin/rails g spree:backend:install

# Run migrations
bin/rails db:create db:migrate

# Load initial data (countries, zones, roles)
bin/rails db:seed

# Optional: sample data
bin/rails spree_sample:load

After this:

• Admin UI is available at /admin (login: [email protected], password: spree123)
• API is available at /api/v2/storefront

Store Configuration

# config/initializers/spree.rb
Spree.config do |config|
  config.currency = "USD"
  config.currency_symbol_position = :before
  config.prices_inc_tax = false
  config.track_inventory_levels = true
  config.require_master_price = true
end

# db/seeds.rb — or rake task on first deploy
store = Spree::Store.create_with(
  name: "My Shop",
  mail_from_address: "[email protected]",
  default_currency: "USD",
  supported_currencies: "USD",
  default_locale: "en",
  supported_locales: "en,fr,de",
  checkout_zone_id: Spree::Zone.find_by(name: "United States")&.id,
  seo_title: "My Shop — online store",
  meta_description: "Store description",
).find_or_create_by!(url: "myshop.com")

Configuring Zones and Shipping

# United States zone
us_country = Spree::Country.find_by!(iso: "US")
us_zone = Spree::Zone.create!(name: "United States", kind: "country")
us_zone.members.create!(zoneable: us_country)

# Tax zone
tax_category = Spree::TaxCategory.create!(name: "Sales Tax 8%", is_default: true)
tax_rate = Spree::TaxRate.create!(
  name: "Sales Tax",
  amount: 0.08,
  included_in_price: false,
  zone: us_zone,
  tax_category: tax_category,
  calculator: Spree::Calculator::DefaultTax.new
)

# Shipping method
shipping_category = Spree::ShippingCategory.create!(name: "Default")
shipping_method = Spree::ShippingMethod.create!(
  name: "UPS Ground",
  admin_name: "ups_ground",
  tracking_url: "https://track.example.com/:tracking"
)
shipping_method.zones << us_zone
shipping_method.shipping_categories << shipping_category
shipping_method.calculator = Spree::Calculator::Shipping::FlatRate.create!(
  preferred_amount: 10.00,
  preferred_currency: "USD"
)

Configuring Sidekiq and Redis

# config/sidekiq.yml
:concurrency: 5
:queues:
  - [critical, 3]
  - [default, 2]
  - [mailers, 1]
  - [low, 1]

# config/application.rb
config.active_job.queue_adapter = :sidekiq

# config/initializers/redis.rb
Redis.current = Redis.new(url: ENV.fetch("REDIS_URL", "redis://localhost:6379/0"))

Docker Compose for Development

# docker-compose.yml
version: "3.9"
services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: spree
      POSTGRES_PASSWORD: spree_dev
      POSTGRES_DB: my_shop_development
    ports: ["5432:5432"]
    volumes: [pgdata:/var/lib/postgresql/data]

  redis:
    image: redis:7-alpine
    ports: ["6379:6379"]

  web:
    build: .
    command: bin/rails server -b 0.0.0.0
    volumes: [.:/app]
    ports: ["3000:3000"]
    depends_on: [postgres, redis]
    environment:
      DATABASE_URL: postgres://spree:spree_dev@postgres/my_shop_development
      REDIS_URL: redis://redis:6379/0

  sidekiq:
    build: .
    command: bundle exec sidekiq
    volumes: [.:/app]
    depends_on: [postgres, redis]
    environment:
      DATABASE_URL: postgres://spree:spree_dev@postgres/my_shop_development
      REDIS_URL: redis://redis:6379/0

volumes:
  pgdata:

API v2: Enabling and Configuration

API v2 is enabled automatically when spree_api is in Gemfile (included in spree):

# config/initializers/cors.rb (for headless)
Rails.application.config.middleware.insert_before 0, Rack::Cors do
  allow do
    origins ENV.fetch("ALLOWED_ORIGINS", "http://localhost:3001").split(",")
    resource "/api/*",
      headers: :any,
      methods: [:get, :post, :patch, :put, :delete, :options],
      credentials: true,
      expose: ["X-Spree-Token"]
  end
end

Checklist After Installation

• Database created, migrations applied
• Seeds loaded (countries, zones, roles)
• Admin UI accessible, password changed
• Store configured (URL, currency, locale)
• Shipping zones and methods created
• Tax rates configured
• Payment methods activated in Admin UI
• Sidekiq running
• ActiveStorage configured (S3 or local folder)
• CORS configured (for headless mode)

Complete installation and initial setup takes 1–2 days with existing infrastructure.