Встановлення і налаштування 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)
• 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

Налаштування магазину

# 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 — або rake-завдання при першому розгортанні
store = Spree::Store.create_with(
  name: "My Shop",
  mail_from_address: "[email protected]",
  default_currency: "USD",
  supported_currencies: "USD",
  default_locale: "uk",
  supported_locales: "uk,en,de",
  checkout_zone_id: Spree::Zone.find_by(name: "Ukraine")&.id,
  seo_title: "My Shop — інтернет-магазин",
  meta_description: "Опис магазину",
).find_or_create_by!(url: "myshop.ua")

Налаштування зон та доставки

# Зона Україна
ua_country = Spree::Country.find_by!(iso: "UA")
ua_zone = Spree::Zone.create!(name: "Ukraine", kind: "country")
ua_zone.members.create!(zoneable: ua_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: ua_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_kyiv",
  tracking_url: "https://track.example.com/:tracking"
)
shipping_method.zones << ua_zone
shipping_method.shipping_categories << shipping_category
shipping_method.calculator = Spree::Calculator::Shipping::FlatRate.create!(
  preferred_amount: 100.00,
  preferred_currency: "USD"
)

Налаштування 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

Контрольний список після встановлення

• БД створена, міграції застосовані
• Seeds завантажені (країни, зони, ролі)
• Admin UI доступен, пароль змінено
• Магазин налаштований (URL, валюта, мова)
• Зони доставки та методи створені
• Податкові ставки налаштовані
• Методи оплати активовані в Admin UI
• Sidekiq запущено
• ActiveStorage налаштовано (S3 або локальна папка)
• CORS налаштовано (для headless режиму)

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