Merge pull request #1926 from will-in-wi/initial_cookbook

Initial attempt at a cookbook

docs/_includes/navigation.html

@@ -34,6 +34,12 @@
   <li><a href="/documentation/getting-started/authentication-and-authorisation/">Authentication &amp; Authorisation</a></li>
   <li class="divider"></li>
 
+  <h5>Task cookbook</h5>
+  <!-- Also add to intro/index.markdown  -->
+  <li><a href="/documentation/tasks/intro/">Introduction</a></li>
+  <li><a href="/documentation/tasks/rails/">Rails related tasks</a></li>
+  <li class="divider"></li>
+
   <h5>Advanced Features</h5>
   <li><a href="/documentation/advanced-features/console/">Console</a></li>
   <li><a href="/documentation/advanced-features/ptys/">PTYs</a></li>

docs/documentation/tasks/intro/index.markdown

@@ -0,0 +1,15 @@
+---
+title: Task Cookbook
+layout: default
+---
+
+These pages document common custom tasks for specific use cases. It is hoped that these will be copied and modified for your use case, and also provide a basis for understanding how to extend Capistrano for your own usage.
+
+You can also look in most Capistrano repositories (including core) for rake tasks to see further example of how it works.
+
+Feel free to contribute more via a Pull Request.
+
+### Pages
+
+<!-- Also add to navigation.html  -->
+* [Rails related tasks](/documentation/tasks/rails/)

docs/documentation/tasks/rails/index.markdown

@@ -0,0 +1,48 @@
+---
+title: Custom Rails Tasks
+layout: default
+---
+
+Many of these tasks probably require [Capistrano::Rails](https://github.com/capistrano/rails).
+
+### Run arbitrary rake tasks from environment variables
+
+From [Capistrano/Rails PR #209](https://github.com/capistrano/rails/pull/209)
+
+```ruby
+namespace :deploy do
+  desc 'Runs any rake task, cap deploy:rake task=db:rollback'
+  task rake: [:set_rails_env] do
+    on release_roles([:db]) do
+      within release_path do
+        with rails_env: fetch(:rails_env) do
+          execute :rake, ENV['task']
+        end
+      end
+    end
+  end
+end
+```
+
+Passes in the rake task to be run via an environment variable. Also a simple example of running a rake task on the server.
+
+```bash
+bundle exec cap production deploy:rake task=db:seed
+```
+
+
+### Conditional migrations
+
+Arising from [Capistrano/Rails issue #199](https://github.com/capistrano/rails/issues/199)
+
+A frequent issue on deploy are slow migrations which involve downtime. In this case, you often want to run the migrations conditionally, where the main deploy doesn't run them, but you can do so manually at a better point. To do so, you could put the following in your `Capfile`:
+
+```ruby
+require 'capistrano/rails/migrations' if ENV['RUN_MIGRATIONS']
+```
+
+Now the migrations do not run by default, but they will run with the following command:
+
+```bash
+RUN_MIGRATIONS=1 bundle exec cap production deploy:migrate
+```