Added guides on new Deployment Service

guides.yml

@@ -30,9 +30,25 @@ index:
     - title: Working with the Source Code
       url: source_code
       text: An Introduction to Working with the Source Code
-    - title: Server Configuration
+  Server Config & Deployment:
+    - title: Overview & Deployment Options
       url: server_configuration
-      text: Steps to get your Spree application up and running in a production environment.
+      text: Overview of Spree's server requirements and deployment options.
+    - title: Spree Deployment Service
+      url: deployment_service
+      text: Detailed walkthrough of using the Deployment Service to build a production environment.
+    - title: Deploying your application
+      url: deploying_your_application
+      text: Explains how to deploy your application to servers that have been configured by the Deployment Service
+    - title: Server Config. & Customization
+      url: server_configuration_and_customization
+      text: Covers the basic configuration of servers built using the deployment service, and how to customize the configuration.
+    - title: Application Processes
+      url: deployment_application_processes
+      text: Details the use of the Foreman gem to define and manage applications processes.
+    - title: Configuration Tips
+      url: deployment_tips
+      text: General troubleshooting and configuration tips
   Basic Configuration:
     - title: Products and Variants
       url: products_and_variants

source/deploying_your_application.textile

@@ -0,0 +1,93 @@
+h2. Deploying Your Application
+
+This article will walk you through configuring and deploying your Spree application to an environment configured with the Deployment Service. 
+
+endprologue.
+
+
+INFO: This guide presumes you are running a Spree version of 0.60.x or later, and that your servers have be built using the "Spree Deployment Service":deployment_service.html
+
+h3. Spree Deploymemnt Dependencies
+
+In order to deploy your application to the standard Deployment Service configuration you will need to add the following to your Gemfile:
+
+<ruby>
+group :production do
+  gem 'unicorn'
+  gem 'mysql2'
+  gem 'foreman'
+  gem 'therubyracer' #only required for 0.70.x or later
+end
+
+group :development do
+  gem 'capistrano'
+end
+</ruby>
+
+Once you saved the Gemfile, run bundle install and commit and push your changes to your remote git repository.
+
+NOTE: Please note it's important to ensure you've committed your Gemfile.lock file also.
+
+h3. Configuring Capistrano
+
+Capistrano is the easiest way to deploy your application to your hosting environment, however you can use any system you prefer. 
+
+The Deployment Service will automatically generate a custom recipe for your environment, specific for your Spree version and including your server(s) and git repository details.
+
+To add the basic Capistrano files to your application run the following command:
+
+<shell>capify .</shell>
+
+This will create the <code>config/deploy.rb</code> file that will contain the details about your server(s), application repository, etc. You can download your Capistrano deploy.rb for each of your configured environments from deployment edit page.
+
+NOTE: The recipe is only available to environment that have chosen "My own custom Spree application", and not the automatic demo store deployment.
+
+Once you've downloaded the automatically generated recipe, replace the contents of your applications <code>config/deploy.rb</code> with it.
+
+
+h4. Configuring authentication for the spree user
+
+The Deployment Service does not automatically set any authentication settings on your servers so you will need to this before continuing, there are two options available:
+
+1. Manually set the spree user's password by running the following command (when logged in as root):
+
+<shell>passwd spree</shell>
+
+2. Avoid password prompt altogether by adding your SSH public key to spree user's authorized_keys file, which can be found here:
+
+<shell>/home/spree/.ssh/authorized_keys</shell>
+
+h4. Deploying for the first time
+
+Once you've completed all the changes above you're ready to deploy your application.
+
+Check everything is configured correctly:
+
+<shell>cap deploy:check</shell>
+
+Do a cold deploy, which checks out the application and migrates the database:
+
+<shell>cap deploy:cold</shell>
+
+If everything worked correctly you should now have your application deployed and database migrated.
+
+INFO: You might want to restore a database dump to configure your data / users / etc.
+
+h3. Troubleshooting
+
+If you're having trouble deploying or starting your application for the first time here's a couple of things to try:
+
+* Review the following log files for indications of the problem:
+## /data/spree/current/log/unicorn.stderr.log
+## /data/spree/current/log/production.log
+## /var/log/nginx/error.log
+## /var/log/spree/web-1.log
+
+* When deploying from private repositories it vital that you have ssh-agent running and your keys added, normally done by executing the following before running `cap`:
+
+<shell>
+  ssh-agent
+  ssh-add
+</shell>
+
+

source/deployment_application_processes.textile

@@ -0,0 +1,115 @@
+h2. Application Processes
+
+This guide will explain how the Spree Deployment Service uses Foreman & Upstart to define and manage all the processes required by your application.
+
+endprologue.
+
+h3. Using Foreman
+
+All application processes are managed using "Foreman":https://github.com/ddollar/foreman and a default Procfile is generated for you in the following location:
+
+<shell>/data/spree/shared/config/Procfile</shell>
+
+By default this includes a single Unicorn master process, the unicorn workers are configured via the Deployment Server UI.
+
+*Default Procfile contents:*
+
+<ruby>web: bundle exec unicorn_rails -c /data/app_name/shared/config/unicorn.rb -p $PORT -E ENV</ruby>
+
+The provided Capistrano deployment script symlinks the Procfile into location after each deploy.
+Capistrano Procfile Snippet:
+
+<ruby>
+namespace :deploy do
+  desc "Symlink shared configs and folders on each release."
+  task :symlink_shared do
+    run "ln -nfs #{shared_path}/config/database.yml #{release_path}/config/database.yml"
+    run "ln -nfs #{shared_path}/config/Procfile #{release_path}/Procfile"
+  end
+end
+
+after 'deploy:update_code', 'deploy:symlink_shared'
+</ruby>
+
+NOTE: It's important to remember to not edit the Procfile above directly, any changes to this file will be reset automatically by our configuration management system. See the "Customizing Processes" section below for more details on how to correctly change this file.
+
+h3. Upstart
+
+After each deployment of your application the Procfile is exported to Upstart compatible configuration files which the operating system (Ubuntu) uses to manage your application's processes.
+
+Upstart is responsible for starting, stopping and restarting the processes and will detect if a process has stopped for some reason and automatically restart it. Upstart does not monitor for memory size growth, and will not restart leaky processes automatically.
+Controlling Processes
+
+Using Upstart you control the processes of application in a number of ways:
+
+h4. All Processes
+
+You can use following commands to start, stop or restart all the processes in your application at once:
+
+<shell>
+sudo stop spree
+sudo start spree
+sudo restart spree
+</shell>
+
+h4. Processes by type
+
+To control all processes of a specific type (for example web, worker, solr, etc) you can use:
+
+<shell>
+sudo start spree-web
+sudo stop spree-worker
+sudo restart spree-solr
+</shell>
+
+h4. Individual Processes
+
+You can control individual processes by prepending the process number (i.e. 1 for first, 2 for second, etc) at the end:
+
+<shell>
+sudo start spree-web-1
+sudo stop spree-worker-3
+sudo restart spree-solr-2
+</shell>
+
+NOTE: The process number is the concurrency number specified in the foreman export, and not the PID.
+
+
+h3. Customizing Processes
+
+To add additional processes such as Delayed Job (or other) workers to your application, complete the following steps:
+
+* Copy the contents of the default Procfile and save it in the root our application.
+* Make any additions or changes you require.
+* Remove the Procfile symlink link line from your config/deploy.rb file.
+* Commit your changes and deploy the application.
+* When your application is deployed the new processes will be automatically started.
+
+*Sample Procfile containing Delayed Job workers:*
+
+<ruby>
+web: bundle exec unicorn_rails -c /data/app_name/shared/config/unicorn.rb -p $PORT -E production
+worker: bundle exec rake jobs:work
+</ruby>
+
+h3. Changing process concurrency
+
+By default the provided Capistrano script will export a single process for each entry in Procfile, for some process types you want to increase the number of processes started, for example Delayed Job workers. You can customize the number of process exported for each process type by editing the foreman:export task in the Capistrano script.
+Custom Capistrano deploy.rb - creating 3 worker processes:
+
+<ruby>
+namespace :foreman do
+  desc "Export the Procfile to Ubuntu's upstart scripts"
+  task :export, :roles => :app do
+    run "cd #{current_path} && bundle exec foreman export upstart /etc/init -a #{application} -c worker=3 -u spree"
+  end
+
+  ... 
+end
+</ruby>
+
+The -c (or --concurrency) switch accepts the process type and an integer for the number of processes to start up. You specify mulitple types by comma separating as follows: processname=2,processname=4
+
+WARNING: Its important to not export more than one :web process when using the default unicorn configuration, as this refers to the master process and not the workers, the worker count can be configured via the Deployment's Service UI.
+
+.

source/deployment_service.textile

@@ -0,0 +1,120 @@
+h2. 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.
+
+endprologue.
+
+h3. 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.
+
+h3. 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).
+
+NOTE: 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.
+
+
+h3. 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.
+
+h3. Using the deployment service
+
+The deployment service can be accessed by via the "Stores":http://spreecommerce.com/stores/ tab under "My Account":http://spreecommerce.com/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 <code>app1.test.com</code> or <code>db1.test.com</code>, 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":server_configuration.html 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.
+
+INFO: 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.
+
+WARNING: 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'"*.
+
+NOTE: 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:
+
+<shell>
+FACTER_db_pass=YOUR_DB_PASSWORD puppet agent --test
+</shell>
+
+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 you application":deploying_your_application.html Guide for more.
+