Установка и настройка Spree Commerce (Ruby on Rails)

Установка и настройка Spree Commerce (Ruby on Rails)

Spree устанавливается в существующее или новое Rails-приложение как Engine. Процесс стандартный, но требует внимания к версиям: Spree 4.x работает на Rails 7.0/7.1, Spree 5.x (beta) — на Rails 7.2+. Ошибки совместимости Gemfile — типичная проблема при установке.

Системные требования

• Ruby 3.1+ (рекомендуется 3.2 LTS)
• Rails 7.0/7.1
• PostgreSQL 13+ (рекомендуется; SQLite только для разработки)
• Redis 6+ (Sidekiq, кэш)
• Node.js 18+ (для Sprockets/importmap или Webpacker legacy)
• ImageMagick или libvips (обработка изображений через ActiveStorage)

Создание нового Rails-приложения

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

# Установить Spree Core
bin/rails g spree:install --user_class=Spree::User

# Установить аутентификацию
bin/rails g spree:auth:install

# Установить Admin UI
bin/rails g spree:backend:install

# Запустить миграции
bin/rails db:create db:migrate

# Загрузить начальные данные (страны, зоны, роли)
bin/rails db:seed

# Опционально: тестовые данные
bin/rails spree_sample:load

После этого:

• Admin UI доступен на /admin (логин: [email protected], пароль: spree123)
• API доступен на /api/v2/storefront

Конфигурация Store

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

# db/seeds.rb — или rake задача при первом деплое
store = Spree::Store.create_with(
  name: "My Shop",
  mail_from_address: "[email protected]",
  default_currency: "RUB",
  supported_currencies: "RUB",
  default_locale: "ru",
  supported_locales: "ru,en",
  checkout_zone_id: Spree::Zone.find_by(name: "Russia")&.id,
  seo_title: "My Shop — интернет-магазин",
  meta_description: "Описание магазина",
).find_or_create_by!(url: "myshop.ru")

Настройка зон и доставки

# Зона Россия
russia_country = Spree::Country.find_by!(iso: "RU")
ru_zone = Spree::Zone.create!(name: "Russia", kind: "country")
ru_zone.members.create!(zoneable: russia_country)

# Зона для налогов
tax_category = Spree::TaxCategory.create!(name: "НДС 20%", is_default: true)
tax_rate = Spree::TaxRate.create!(
  name: "НДС",
  amount: 0.20,
  included_in_price: false,
  zone: ru_zone,
  tax_category: tax_category,
  calculator: Spree::Calculator::DefaultTax.new
)

# Метод доставки
shipping_category = Spree::ShippingCategory.create!(name: "Default")
shipping_method = Spree::ShippingMethod.create!(
  name: "Курьером по Москве",
  admin_name: "courier_moscow",
  tracking_url: "https://track.example.com/:tracking"
)
shipping_method.zones << ru_zone
shipping_method.shipping_categories << shipping_category
shipping_method.calculator = Spree::Calculator::Shipping::FlatRate.create!(
  preferred_amount: 300,
  preferred_currency: "RUB"
)

Настройка Sidekiq и 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 для разработки

# 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: включение и конфигурация

API v2 включается автоматически при наличии spree_api в Gemfile (входит в spree):

# config/initializers/cors.rb (для 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 после установки

• БД создана, миграции применены
• Seeds запущены (страны, зоны, роли)
• Admin UI доступен, пароль изменён
• Store настроен (URL, валюта, локаль)
• Shipping zones и методы созданы
• Tax rates настроены
• Payment methods активированы в Admin UI
• Sidekiq запущен
• ActiveStorage настроен (S3 или локальная папка)
• CORS настроен (для headless режима)

Полная установка и первичная настройка занимает 1–2 дня при наличии готовой инфраструктуры.