Deploying Spree Commerce

Introduction

Spree Commerce is a powerful, open-source e-commerce platform built with Ruby on Rails. Known for its flexibility and developer-friendly architecture, Spree has powered thousands of online stores ranging from small boutiques to large enterprises. Its modular design allows developers to customize every aspect of the shopping experience.

With an API-first approach, Spree works as a headless commerce solution, allowing you to build custom storefronts using any frontend technology while leveraging Spree’s robust backend for product management, orders, payments, and shipping.

Key highlights of Spree Commerce:

• API-First Architecture: RESTful and GraphQL APIs for headless commerce
• Ruby on Rails: Built on a proven, mature framework
• Modular Design: Extend functionality with gems and extensions
• Multi-Store Support: Run multiple storefronts from one installation
• Multi-Currency: Support international customers with multiple currencies
• Multi-Language: Built-in internationalization support
• Payment Gateways: Integrates with Stripe, PayPal, Braintree, and more
• Shipping Integrations: Connect with major shipping carriers
• Tax Calculation: Automatic tax calculation with various providers
• Admin Dashboard: Comprehensive backend for store management
• Inventory Management: Track stock levels across locations
• Open Source: BSD-3-Clause license with active community

This guide walks through deploying Spree Commerce on Klutch.sh using Docker for a production-ready e-commerce platform.

Why Deploy Spree Commerce on Klutch.sh

Deploying Spree Commerce on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh handles the Rails application deployment automatically.

Persistent Storage: Product images, database, and uploads persist across deployments.

HTTPS by Default: Secure checkout with automatic SSL certificates.

GitHub Integration: Version control your store and deploy updates automatically.

Scalable Resources: Allocate resources based on traffic and catalog size.

Environment Variable Management: Securely store payment gateway keys and secrets.

Custom Domains: Use your brand’s domain for the storefront.

High Availability: Keep your store running 24/7 for customers worldwide.

Prerequisites

Before deploying Spree Commerce on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your store
• PostgreSQL database (can be deployed on Klutch.sh or external)
• Redis instance for caching and background jobs
• Basic familiarity with Ruby on Rails and Docker
• (Optional) Payment gateway credentials (Stripe, PayPal, etc.)
• (Optional) A custom domain for your store

Deploying Spree Commerce on Klutch.sh

Create a GitHub Repository

Create a new GitHub repository for your Spree Commerce store, or fork the official Spree starter.

Create Your Dockerfile

Create a Dockerfile in your repository:

FROM ruby:3.2-slim

# Install dependencies
RUN apt-get update && apt-get install -y \
    build-essential \
    libpq-dev \
    nodejs \
    npm \
    git \
    imagemagick \
    libvips-dev \
    && rm -rf /var/lib/apt/lists/*

# Install Yarn
RUN npm install -g yarn

WORKDIR /app

# Install Ruby dependencies
COPY Gemfile Gemfile.lock ./
RUN bundle install --jobs 4 --retry 3

# Install JavaScript dependencies
COPY package.json yarn.lock ./
RUN yarn install

# Copy application code
COPY . .

# Precompile assets
RUN RAILS_ENV=production SECRET_KEY_BASE=dummy bundle exec rails assets:precompile

# Create necessary directories
RUN mkdir -p /app/storage /app/tmp/pids

EXPOSE 3000

HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
  CMD curl -f http://localhost:3000/up || exit 1

CMD ["bundle", "exec", "rails", "server", "-b", "0.0.0.0", "-p", "3000"]

Create or Update Gemfile

Ensure your Gemfile includes Spree:

source 'https://rubygems.org'

ruby '3.2.0'

gem 'rails', '~> 7.1'
gem 'spree', '~> 4.7'
gem 'spree_backend', '~> 4.7'
gem 'spree_emails', '~> 4.7'
gem 'spree_sample', '~> 4.7'
gem 'spree_auth_devise', '~> 4.6'
gem 'spree_gateway', '~> 3.10'

gem 'pg', '~> 1.5'
gem 'redis', '~> 5.0'
gem 'sidekiq', '~> 7.0'
gem 'puma', '~> 6.0'

Push Your Repository to GitHub

Commit and push your store code.

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project.

Create a New App

Within your project, create a new app and connect your GitHub repository.

Configure HTTP Traffic

In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 3000

Set Environment Variables

Configure the following environment variables:

Variable	Value
RAILS_ENV	production
SECRET_KEY_BASE	Generate with rails secret
DATABASE_URL	PostgreSQL connection string
REDIS_URL	Redis connection string
RAILS_SERVE_STATIC_FILES	true
RAILS_LOG_TO_STDOUT	true

Attach Persistent Volumes

Add the following volumes:

Mount Path	Recommended Size	Purpose
/app/storage	50 GB	Product images and uploads
/app/public/assets	5 GB	Compiled assets

Deploy Your Application

Click Deploy to build and start Spree Commerce.

Run Database Migrations

After the first deployment, run database setup via the Klutch.sh console or a one-time job:

bundle exec rails db:create db:migrate
bundle exec rails spree:install:seed

Access Your Store

Once deployment completes, access your store at https://your-app-name.klutch.sh.

Initial Configuration

Creating Admin User

Create an admin account:

bundle exec rails spree:user:admin:create

Or through the Rails console:

Spree::User.create!(
  email: 'admin@example.com',
  password: 'password123',
  spree_roles: [Spree::Role.find_or_create_by(name: 'admin')]
)

Admin Dashboard Access

Access the admin dashboard at https://your-store.klutch.sh/admin with your admin credentials.

Basic Store Setup

1. Configure store settings (name, currency, timezone)
2. Set up shipping zones and methods
3. Configure tax categories and rates
4. Add payment methods

Payment Gateway Configuration

Stripe Integration

Add to environment variables:

Variable	Value
STRIPE_PUBLISHABLE_KEY	Your Stripe publishable key
STRIPE_SECRET_KEY	Your Stripe secret key

Configure in admin panel under Payment Methods.

PayPal Integration

Configure PayPal credentials similarly and enable in the admin dashboard.

Product Management

Adding Products

Through the admin dashboard:

1. Navigate to Products
2. Click Add Product
3. Fill in product details
4. Upload images
5. Set pricing and inventory
6. Publish the product

Product Categories

Organize products with taxonomies:

1. Go to Products then Taxonomies
2. Create categories and subcategories
3. Assign products to categories

Inventory Management

Track stock levels:

• Set stock for each variant
• Configure backorder settings
• Enable/disable inventory tracking

Customization

Themes and Storefronts

Spree supports multiple frontend options:

• Spree Storefront: Default Rails views
• Headless: Use React, Vue, or Next.js with the API
• Mobile Apps: Build native apps using the API

Extensions

Popular Spree extensions:

Extension	Purpose
spree_multi_vendor	Marketplace functionality
spree_reviews	Product reviews
spree_wishlist	Customer wishlists
spree_social	Social login
spree_analytics	Analytics tracking

Background Jobs

Sidekiq Configuration

For background job processing, deploy a separate worker process:

worker.Dockerfile

FROM your-spree-image

CMD ["bundle", "exec", "sidekiq"]

Common Background Jobs

• Order confirmation emails
• Inventory updates
• Report generation
• Search indexing

Troubleshooting

Assets Not Loading

• Verify RAILS_SERVE_STATIC_FILES is set
• Check asset compilation succeeded
• Ensure persistent volume is mounted

Database Connection Failed

• Verify DATABASE_URL is correct
• Check database server is accessible
• Ensure database exists

Payment Processing Issues

• Verify payment gateway credentials
• Check webhook configuration
• Review payment gateway logs

Additional Resources

• Spree Commerce Official Site
• Spree Developer Documentation
• Spree GitHub Repository
• Spree API Documentation
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying Spree Commerce on Klutch.sh gives you a powerful, customizable e-commerce platform with automatic builds, persistent storage, and secure HTTPS. Whether you’re building a simple online store or a complex multi-vendor marketplace, Spree’s flexibility and Klutch.sh’s deployment simplicity provide a solid foundation for your e-commerce business.