More at Features | Support | Blog | Demo | Community | Download

Server Configuration

This guide is intended to provide assistance in setting up Spree in a production server environment. After reading it, you should be familiar with:

1 Overview

Spree is essentially a Rails application so we will not be getting into a lot of detail related to deploying a Rails application. The official Rails website lists some deployment options to help get you started. This guide will be focused on providing a few time-saving tips related to deployment and answering some common problems people encounter with their server setups.

This guide also assumes basic familiarity with Spree. Please refer to the Getting Started Guide for details on how to get up and running for Spree. You will have an easier time understanding the extra complications of a production setup.

2 Typical Configuration Options

2.1 Serving Public Assets

Rails applications (including Spree) use the convention of storing public assets (images, javascripts, stylesheets, etc.) in a directory named public. In development environments, Rails itself will automatically handle requests for this static content by serving it from the public directory. In production mode, however, Rails is not configured to serve public assets unless specifically enabled. This leaves you with two options.

2.1.1 Configure Rails to Serve Public Assets

Rails has a config.serve_static_assets setting that allows you to override its default behavior in the production environment. If you want Rails to serve you public assets you will need to change this setting in config/environments/production.rb of your Rails app as follows:

config.serve_static_assets = true

There is a good reason why this is disabled by default in Rails which is that Rails is not a general purpose web server. Servers such as Apache and Nginx are optimized for rapidly serving up static content. You should consider the advice of the Rails core team and let your webserver do what it does best (as described in the next section.)

2.1.2 Configure the Web Server to Use the public Directory

The recommended approach for handling static assets is to allow your web server to handle serving these files. If you want to follow this approach just make sure that its configured properly in the config/environments/production.rb of your Rails app.

config.serve_static_assets = false

This is the default setting of Rails so its also fine if this setting is missing or commented out.

The following is an example of how to configure Apache so that its document root is pointing to the public folder.

<VirtualHost *:80> ServerName DocumentRoot /webapps/mystore/public <Directory /webapps/mystore/public> Allow from all Options -MultiViews </Directory> </VirtualHost>

Each web server will have its own method for doing this so please consult the appropriate documentation for more details.

2.2 Enabling SSL

Spree supports SSL and contains a special filter to require SSL for certain sensitive pages (checkout and admin-related.) It also has the ability to redirect SSL requests that do not require SSL back to standard unencrypted HTTP. The code for this is built right into Spree and is based on the ssl_requirement by David Heinemeier Hansson.

The default behavior for Spree depends on the Rails environment are as follows:

Environment SSL Enabled
Development False
Test False
Staging True
Production True

The “staging” environment is not one of the default environments created by Rails. Many developers, however, add this environment which is designed to mimic the production environment behavior as much as possible. You can still, however, make minor changes such as disabling email or sending email to a test account instead of the designated recipient.

2.2.1 SSL Preferences

SSL behavior in Spree is determined by two different preferences.

Preference Default Value
allow_ssl_in_production true
allow_ssl_in_development_and_test false

For more information on preferences in general you may wish to read the Preference Guide.

2.2.2 Changing the Default Settings

If you do not wish to use SSL in production, or if you wish to enable SSL in development mode, you will have to change the :allow_ssl_in_production configuration setting. This can be done via the admin interface (Configuration | General Settings) as shown below, but it is usually better to use an initializer.

[TODO: include reference to discussion on initializers/customization]

Changing SSL Setting

2.2.3 SSL with Mongrel

Mongrel relies on Apache to tell it which requests are HTTP and which are HTTPS. If you do not set things up correctly you’re likely to experience an infinite loop. You will need to change the Port 443 configuration of your Apache virtual host (NOTE: Port 443 not Port 80) and add the following line:

RequestHeader set X_FORWARDED_PROTO 'https'

You can read more about this topic (and more on testing SSL locally on your development machine) in Mike Subelsky’s excellent blog post

[TODO: Verify this is still necessary with Mongrel since this issue was discovered a long time ago]

2.3 Configuring Email Options

Mail delivery in Spree is disabled by default. Enabling it is simple procedure that is generally done via the admin interface (Configuration | Mail Methods) as shown below.

Changing Mail Server Setting

[TODO: Update image with new screenshot]

To properly enable email delivery, you need to provide valid SMTP information. This includes the following:

  1. SMTP Domain
  2. SMTP Mail Host
  3. SMTP Port
  4. Secure Connection Type
  5. SMTP Authentication Type
  6. SMTP Username
  7. SMTP Password

Note that mail settings are configured on a per-environment basis. This will allow you to configure the settings differently for staging or production mode. For example, you might want to intercept all outgoing email in the staging environment and re-route it to This would prevent someone from accidentally sending an email to a real world customer when testing operations such as canceling an order or marking it shipped.

Its generally considered a bad idea to send email on the same “thread” as a web request. Many web applications (including e-commerce ones) manage to get by doing this but high volume stores should consider using standard Rails techniques such as Delayed Job for handling email delivery as a separate process.

The Spree core team is actively working on a solution for improved email processing - perhaps involving an optional extension for Delayed Job support.

Spree overrides the default configuration of email by Rails and will ignore whatever settings you may have in your Rails application. This is to allow easier configuration of email by non-programmers through an admin interface. Spree also uses this mechanism to provide a few additional settings that are not supplied by Rails.

3 Performance Tips

3.1 Running in Production Mode

If you are noticing that Spree seems to be running slowly you should make sure that you are running in “production mode.” You can start your server in production mode as follows:

rails server -e production

Please consult your web server documentation for more details on enabling production mode for your particular web server.

3.2 Passenger Timeout

If you are running on Passenger then you may be noticing that the first request to your Spree application is very slow if the application has been idle for some time (or you have just restarted.) Consider changing the PassengerPoolIdleTime as described in the Passenger documentation.

3.3 Caching

Most stores spend a lot of time serving up the same pages over and over again. In many cases, the content being served is exactly identical or nearly identical for every user. In such cases, a caching solution may be appropriate and can improve server performance by bypassing time consuming operations such as database access. Rails provides several excellent caching options that you should consider investigating.

A detailed description of Rails caching is beyond the scope of this guide.

The Spree core team is actively considering some form of basic caching support to make it easier to leverage the Rails caching options.

4 Specific Hosting Providers

The following is a collection of tips that are specific to certain hosting providers.

4.1 Heroku

[TODO: Discussion of stylesheet caching, etc.]

[TODO: Give example on configuring S3 buckets]