This guide is intended to provide some generally useful hints and tips\ for troubleshooting standard deployment issues, including:
- How static assets are served in production
- Enabling & Configuringn SSL use within Spree
- Email configuration
- and more …
Serving Static Assets
Rails applications (including Spree) use the convention of storing
public. In development environments, Rails itself will
automatically handle requests for this static content by serving it from
public directory. In production mode, however, Rails is not
configured to serve public assets unless specifically enabled. This
leaves you with two options.
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.)
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 it’s 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 it’s 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
<VirtualHost *:80> ServerName www.mystore.com 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.
Spree supports SSL and contains a special filter to require SSL for certain sensitive pages 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 as follows:
The “staging” environment is not one of the default environments created by Rails. However, many developers use a staging environment, which generally should mimic the production environment as much as possible. You may, however, make minor changes such as disabling email or sending email to a test account instead of the designated recipient.
SSL behavior in Spree is determined by several different preferences.
For more information on preferences in general you may wish to read the Preference Guide.
Changing the Default Settings
If you do not wish to use SSL in production or staging, 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 as shown below:
If you need to change any of the above default settings, it is also
recommended to fix the setting in an initializer . In
/config/initializers/spree.rb, add a line such as:
config.allow_ssl_in_staging = false
Configuring Email Options
Mail delivery in Spree is disabled by default. You can enable it in two ways.
First, if you need to keep your default Rails app action mailer configs you need to tell Spree to not override them by setting the
override_actionmailer_config option to
false. You should also tell Spree which email should go on the header from using the
mails_from option. A typical spree initializer which disables all Spree default mail settings and interceptor looks like this:
Spree.config do |config| config.override_actionmailer_config = false config.mails_from = "[email protected]" end
Secondly, in case you want to use Spree admin UI or config options via initializer to properly enable email delivery, you need to provide valid SMTP information. This includes the following (spree config options goes along):
- SMTP Domain (mail_domain, defaults to localhost)
- SMTP Mail Host (mail_host, defaults to localhost)
- SMTP Port (mail_port, defaults to 25)
- Secure Connection Type (secure_connection_type, defaults to None)
- SMTP Authentication Type (mail_auth_type, defaults to None)
- SMTP Username (smtp_username, defaults to nil)
- SMTP Password (smtp_password, defaults to nil)
Those can be updated either by an usual spree initializer block or through admin UI. You could set them as per environment as well. e.g.
Spree.config do |config| if Rails.env.production? config.mail_port = 1025 # other configs .. else config.mail_port = 25 # other configs .. end end
Regardless of whether you decide to configure ActionMailer via the admin
UI or an initializer, you may decide that while you need to have mail
capabilities for other parts of your app, you don’t want to send Spree’s
default email notifications (e.g. order confirmation). This may be the
case if you use a transactional email service like Mandrill for such
notifications but you require regular ActionMailer capabilities for
other parts of your app. If this is the case you can change the default
true value for the
send_core_emails config to
override_actionmailer_config value also gives you the chance
to set bcc headers for all spree outgoing emails and to intercept them and
reroute to someone else. This could come in handy on staging servers since
it prevents the store from accidentally sending emails to a real world
customer when testing operations such as canceling an order or marking it
shipped. At last you need to set
enable_mail_delivery = true
as it defaults to
Spree.config do |config| config.enable_mail_delivery = true config.mail_bcc = "[email protected]" if Rails.env.staging? config.intercept_email = "[email protected]" end end
Both smtp and inteceptor configs listed above can be found on the mail section
in the configuration tab. Note that the Mail Method Setting link will not
be displayed if
It’s generally considered a bad idea to send email on the same “thread” as a web request. Many web applications 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.
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:
$ bundle exec rails server -e production
Please consult your web server documentation for more details on enabling production mode for your particular web server.
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.
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.