Spree Deployment Service

This guide will explain the terms and features provided by the Spree Deployment Service, after reading this you will be familiar with:

  • The different roles available for configuring servers.
  • Typical role combinations used for single and multi-server environments
  • How to add a deployment, and configure your servers using it.

1 Spree Deployment Service

The Spree Deployment Service is a free tool that allows you to configure and deploy the Spree Software Stack on any dedicated cloud, virtual private or physical server.

The service can be configured to create single and multi-server configurations on a wide range of Linux based operating systems, and supports deploying demo Spree applications or generating Capistrano recipes for deploying your own application.

2 Understanding server roles

The Deployment Service supports a wide range of configuration topologies by allowing you to choose individual roles for each server within your deployment.

Each role installs and configures different software packages on the target server, and a server can have one or more roles applied.

Available roles currently include:

  • Application Server - Installs and configures Nginx, Ruby, and more. Every deployment requires at least one Application Server, but can have as many as required.
  • Database Server - Installs and configures MySQL, Ruby. Only one Database Server can be configured for a deployment.
  • Utility Server - Installs and configures Ruby. A deployment can have as many Utility Servers as needed, but a Utility Server role cannot be shared with any other role. Utility Servers generally run Delayed Job workers, Solr indexes, Redis or Memcache services but these applications must be configured manually and will not be installed by the Deployment Service.
  • Load Balancer - Can only be applied to an Application Server and configures Nginx to load balance Rails requests to all applications servers unicorn back ends. The Load Balancer will handle all requests for static assets (stylesheets, javascripts, images, etc).

Every server will get some basic configuration, such as Rails Environment environment variable, placeholder directories for your Spree application, automatically generated database.yml and Procfile files, and more.

3 Typical server role combinations

For a Single Server deployment, you would select Application and Database as the two roles for your single server.

For Multi Server deployments, you would generally select the following:

  • At least one dedicated Application Server.
  • One dedicated Database Server.
  • One application server can be designated as the Load Balancer if you have more that one application server (and you are not using a third party load balancing service).
  • Any number of Utility Servers as required by your application.

4 Using the deployment service

The deployment service can be accessed by via the Stores tab under My Account.

Each Store can have one or more “deployments” configured (for production, staging or qa environments), and each deployment can have one or more servers.

To create a deployment:

1. Add a new Store or click on an existing store, and choose the “Add Deployment Service” link.

Each deployment has a number of global parameters which affects all servers configured within that environment including:

  • Operating System - Currently only Ubuntu / Debian flavours are supported, with Ubuntu 10.04 LTS the preferred version.
  • Rails Environment - Sets the server wide rails environment, default ‘production’.
  • Ruby Version - Select the preferred Ruby version you would like installed.
  • Spree Version - If you choose to install a sample application (see below), the Spree version selected here will be the one used by the sample app. If you choose to deploy your own custom application, the Spree Version affects the Capistrano Recipe that gets generated.
  • What would you like deployed - Choose “A Sample Application” if you do not have a Spree application ready to deploy, or “My own custom Spree application” if you do.
  • Git URL for your application - Only available when deploying your own application and this value is only used to complete your generated Capistrano Recipe.

2. Once you’ve configured the global environments details, click “Add” to save the configuration.

Now you need to provide details on each server that’s included in the environment:

  • Fully Qualified Domain Name (FQDN) - This should be something like app1.test.com or db1.test.com, it does not need to be registered or resolvable it is purely used for naming purposes.
  • IP Address - It’s important to supply the correct IP address as it’s referenced in several locations within the configuration and supplying an invalid value will result in problems with the configuration. You can use internal / private addresses for your servers as the only requirement is that all servers can communicate with each other using the addresses supplied.
  • Unicorn Workers - This value is only required for servers with the Application Server role, and controls how many worker processes the unicorn master process will fork on startup. Setting this value correctly is important, see the Overview & Deployment Options Guide for details on memory requirements / workers.
  • Roles - Select the required roles for the server, see the Understanding Server Roles section above for more details.

3. When you’ve added the details for all the servers in your deployment, you should then change the Configuration Status from “New” to “Complete”.

This will upload your server configurations to our deployment server, which may take a few moments. Refresh the page occasionally until you see each servers Status change from “Waiting for update from configuration server.” to “Ready to Deploy”.

4. Now each server will have a Initialize Configuration command that must be copied and executed on the relevant server.

This needs to be done as root user, and can take several minutes to complete.

It’s important to be aware that while all the Initialize Configurations commands appear similar they are server specific so be sure to run the correct command on each server.

The Initialize Configuration command should only be run on servers that are intended to be dedicated Spree servers, it reconfigures large parts of the server to fulfill it’s assigned roles and many affect any other applications, configuration or data already present on a server.

5. When the initialize configuration command completes the server will report it’s result and you should see each server’s Status eventually update to “Reported as ‘changed’”.

If an error occurs during the build the status might not update or it may update as “Reported as ‘failed’”, in either event you should attempt to run the Update Configuration command listed.

6. Finally when all servers have reported as either ‘changed’ or ‘unchanged’ the final step is to run the Update configuration command to set your site specific database passwords.

The command is generally something like:

FACTER_db_pass=YOUR_DB_PASSWORD puppet agent --test

It’s important to substitute YOUR_DB_PASSWORD with the actual password you require.

7. Congratulations you now have a fully configured environment ready for use.

If you choose to deploy a “Sample Application” then you should be able to browser to your Application Servers IP address to view the store running.

If you are deploying your own application, please refer to the Deploying your application Guide for more.

This project is maintained by a core team of developers and is freely available for commercial use under the terms of the New BSD License.