recap 0.2.0 → 1.0.0

data/lib/recap/tasks/bootstrap.rb

@@ -0,0 +1,77 @@
+# Recap has a number of requirements on your server before you can deploy applications
+# with it.  These include:
+#
+# - Each application needs its own account on the server.  The full account environment
+#   is loaded whenever an application command or process is run, so this is the place where
+#   other application specific configuration should happen.
+# - Each deploying user needs a personal account on the server which they should be able to
+#   ssh into.
+# - This personal account needs to be able to `sudo`, both to switch to the application user
+#   and to run other administrative commands.
+
+require 'recap/tasks'
+
+module Recap::Tasks::Bootstrap
+  extend Recap::Support::Namespace
+
+  # The bootstrap namespace has a couple of task that help configure application and personal accounts
+  # and personal accounts to meet these requirements.
+  namespace :bootstrap do
+    set(:remote_username) { capture('whoami').strip }
+    set(:application_home) { "/home/#{application_user}"}
+
+    # The `bootstrap:application` task sets up the account on the server the application itself uses.  This
+    # account should be dedicated to running this application.
+    desc 'Sets up the server account used by the application, including home directory and environment support'
+    task :application do
+      # If the account doesn't already exist on the server, the task creates it.
+      if exit_code("id #{application_user}").strip != "0"
+        sudo "useradd #{application_user} -d #{application_home}"
+      end
+
+      # If the home directory doesn't exist, or isn't both readable and writable by members of the application
+      # group (all the accounts allowed to deploy the app) then the task creates the directory and fixes
+      # file permissions.
+      sudo "mkdir -p #{application_home}"
+      sudo "chown #{application_user}:#{application_group} #{application_home}"
+      sudo "chmod 755 #{application_home}"
+
+      # A script `.recap` is added to set the configuration environment (set with `env:set` and
+      # `env:edit` tasks).  The script loads the `.env` file in the users home folder, creates
+      # a new copy with `export ` prefixed to each line, and sources this new copy.
+      put_as_app %{
+if [ -s "$HOME/.env" ]; then
+  sed -e 's/\\r//g' -e 's/^/export /g' .env > .recap-env-export
+  . $HOME/.recap-env-export
+fi
+      }, "#{application_home}/.recap"
+
+      # Finally, `.profile` needs to source the `.recap` script, so that the configuration environment is
+      # available whenever the environment is loaded.
+      as_app "touch .profile", "~"
+
+      if exit_code("grep '\\. $HOME/\\.recap' #{application_home}/.profile") != "0"
+        as_app %{echo ". \\$HOME/.recap" >> .profile}, "~"
+      end
+    end
+
+    # The `bootstrap:user` task sets up the personal accounts of user who can deploy applications.
+    # In order to deploy a particular app, the account's git configuration must be set (so
+    # that releases can be tagged), and the account must be a member of the application group.
+    desc 'Sets up the server account used by a deploying user'
+    task :user do
+      git_user_name = Recap::Support::ShellCommand.execute("git config user.name").strip
+      git_user_email = Recap::Support::ShellCommand.execute("git config user.email").strip
+      run "git config --global user.name '#{git_user_name}'"
+      run "git config --global user.email '#{git_user_email}'"
+      sudo "usermod --append -G #{application_group} #{remote_username}"
+    end
+
+    # The `bootstrap` task simply runs both the `bootstrap:application` and `bootstrap:user` tasks
+    # in turn.
+    task :default do
+      application
+      user
+    end
+  end
+end

data/lib/recap/{bundler.rb → tasks/bundler.rb}

@@ -1,10 +1,12 @@
 # The bundler recipe ensures that the application bundle is installed whenever the code is updated.
 
-module Recap::Bundler
-  extend Recap::Namespace
+require 'recap/tasks'
+
+module Recap::Tasks::Bundler
+  extend Recap::Support::Namespace
 
   namespace :bundle do
-    # Each bundle is declared in a `Gemfile`, by default in the root of the application directory
+    # Each bundle is declared in a `Gemfile`, by default in the root of the application directory.
     set(:bundle_gemfile) { "#{deploy_to}/Gemfile" }
 
     # As well as a `Gemfile`, application repositories should also contain a `Gemfile.lock`.
@@ -16,7 +18,7 @@ module Recap::Bundler
 
     # Not all gems are needed for production environments, so by default the `development`, `test` and
     # `assets` groups are skipped.
-    set(:bundle_without) { "development test assets" }
+    set(:bundle_without) { "development test" }
 
     # The main bundle install command uses all the settings above, together with the `--deployment`,
     # `--binstubs` and `--quiet` flags
@@ -32,7 +34,7 @@ module Recap::Bundler
       end
 
       # Occassionally it's useful to force an install (such as if something has gone wrong in
-      # a previous deployment)
+      # a previous deployment).
       desc "Install the latest gem bundle"
       task :default do
         if deployed_file_exists?(bundle_gemfile)
@@ -47,9 +49,16 @@ module Recap::Bundler
       end
     end
 
+    task :check_installed do
+      if exit_code_as_app('bundle --version', '.') != "0"
+        abort "The application user '#{application_user}' cannot execute `bundle`.  Please check you have bundler installed."
+      end
+    end
+    after 'preflight:check', 'bundle:check_installed'
+
     # To install the bundle automatically each time the code is updated or cloned, hooks are added to
     # the `deploy:clone_code` and `deploy:update_code` tasks.
     after 'deploy:clone_code', 'bundle:install:if_changed'
     after 'deploy:update_code', 'bundle:install:if_changed'
   end
-end
+end

data/lib/recap/{deploy.rb → tasks/deploy.rb}

@@ -1,19 +1,26 @@
-require 'recap'
-require 'recap/capistrano_extensions'
+# These tasks provide the basic mechanism getting new code onto servers using git.
 
-require 'recap/preflight'
-require 'recap/bootstrap'
-require 'recap/env'
+require 'recap/tasks'
+require 'recap/support/capistrano_extensions'
 
-module Recap::Deploy
-  extend Recap::Namespace
+# These deployment tasks are designed to work alongside the tasks for
+# [altering environment variables](env.html), as well as the
+# [preflight checks](preflight.html) and
+# [bootstrap tasks](bootstrap.html).
+
+require 'recap/tasks/env'
+require 'recap/tasks/preflight'
+require 'recap/tasks/bootstrap'
+
+module Recap::Tasks::Deploy
+  extend Recap::Support::Namespace
 
   namespace :deploy do
     # To use this recipe, both the application's name and its git repository are required.
     set(:application) { abort "You must set the name of your application in your Capfile, e.g.: set :application, 'tomafro.net'" }
-    set(:repository) { abort "You must set the git respository location in your Capfile, e.g.: set :respository, 'git@github.com/tomafro/tomafro.net'"}
+    set(:repository) { abort "You must set the git respository location in your Capfile, e.g.: set :respository, 'git@github.com/tomafro/tomafro.net'" }
 
-    # The recipe assumes that the application code will be run as a dedicated user.  Any any user who
+    # The recipe assumes that the application code will be run as a dedicated user.  Any user who
     # can deploy the application should be added as a member of the application's group.  By default,
     # both the application user and group take the same name as the application.
     set(:application_user) { application }
@@ -23,8 +30,8 @@ module Recap::Deploy
     set(:branch, 'master')
 
     # Unlike a standard capistrano deployment, all releases are stored directly in the `deploy_to`
-    # directory.  The default is `/home/#{application_user}/apps/#{application}`.
-    set(:deploy_to)   { "/home/#{application_user}/apps/#{application}" }
+    # directory.  The default is `/home/#{application_user}/app`.
+    set(:deploy_to)   { "/home/#{application_user}/app" }
 
     # Each release is marked by a unique tag, generated with the current timestamp.  While this can be
     # changed, it's not recommended, as the sort order of the tag names is important; later tags must
@@ -47,16 +54,21 @@ module Recap::Deploy
     # `:pty` is set to `true`.
     default_run_options[:pty] = true
 
-    # The `deploy:setup` task prepares all the servers for the deployment.
+    # The `deploy:setup` task prepares all the servers for the deployment.  It ensures the `env`
+    # has been set, and clones the code.
     desc "Prepare servers for deployment"
     task :setup, :except => {:no_release => true} do
       transaction do
+        top.env.set
         clone_code
       end
     end
 
-    # Clone the repository into the deployment directory.
+    # The `deploy:clone_code` task clones the project repository into the `deploy_to` location
+    # and ensures it has the correct file permissions.  It shouldn't be necessary to call this
+    # task manually as it is run as part of `deploy:setup`.
     task :clone_code, :except => {:no_release => true} do
+      on_rollback { as_app "rm -fr #{deploy_to}" }
       # Before cloning, the directory needs to exist and be both readable and writable by the application group
       as_app "mkdir -p #{deploy_to}", "~"
       as_app "chmod g+rw #{deploy_to}"
@@ -64,11 +76,12 @@ module Recap::Deploy
       git "clone #{repository} ."
     end
 
-    # The main deployment task (called with `cap deploy`) deploys the latest application code to all
-    # servers, tags the release and restarts the application.
+    # The `deploy` task ensures the environment is set, updates the application code,
+    # tags the release and restarts the application.
     desc "Deploy the latest application code"
     task :default do
       transaction do
+        top.env.set
         update_code
         tag
       end
@@ -111,8 +124,8 @@ module Recap::Deploy
       end
     end
 
-    # In case of emergency or when manually testing deployment, it can be useful to remove all
-    # previously deployed files before starting again.
+    # The `destroy` task can be used in an emergency or when manually testing deployment.  It removes
+    # all previously deployed files, leaving a blank slate to run `deploy:setup` on.
     desc "Remove all deployed files"
     task :destroy do
       sudo "rm -rf #{deploy_to}"

data/lib/recap/tasks/env.rb

@@ -0,0 +1,111 @@
+# Recap encourages the storage of application configuration (such as database passwords, S3 keys and
+# other things that change between deploys) in environment variables.
+# [12factor.net](http://www.12factor.net) has [http://www.12factor.net/config](a good set of reasons
+# why this is desirable).
+#
+# To enable this, [recap](https://github.com/freerange/recap) stores these configuration variables
+# in `.env`, and adds a script to the user's `.profile` to set these whenever the environment is
+# loaded (see [bootstrap](bootstrap.html)).
+#
+# Variables can be set in two ways.  First, using either the `env:set` or `env:edit` tasks,
+# the `.env` file can be directly manipulated.  This is generally the best way to manipulate
+# these values.
+#
+# The other way to set them is using the `set_default_env` method directly in your `Capfile`.
+# This sets a default value, which will be used if no other value is set.  An example where
+# this might be useful is where you know your app should run using ruby 1.8.7.  Using
+# `set_default_env :RBENV_VERSION, "1.8.7-p352"` in your `Capfile` will use this ruby as the default.
+# Then, in a different deployment you might want to test using a different version of ruby,
+# so could use `cap env:set RBENV_VERSION=1.9.3-p0` to override the default.
+
+require 'recap/tasks'
+
+module Recap::Tasks::Env
+  extend Recap::Support::Namespace
+
+  namespace :env do
+    set(:environment_file) { "/home/#{application_user}/.env" }
+
+    # The `env` task displays the current configuration environment.  Note that this doesn't
+    # include all environment variables, only those stored in the `.env` file.
+    desc 'View the current server environment'
+    task :default do
+      if current_environment.empty?
+        puts "There are no config variables set"
+      else
+        puts "The config variables are:"
+        puts
+        puts current_environment
+      end
+    end
+
+    # A single variable can be set using the `env:set` task, followed by a variable and value,
+    # for example `cap env:set VARIABLE=VALUE`.  Variables can be unset using `cap env:set VARIABLE=`.
+    desc 'Set a variable in the environment, using "cap env:set VARIABLE=VALUE".  Unset using "cap env:set VARIABLE="'
+    task :set do
+      env = env_argv.inject(current_environment) do |env, string|
+        env.set_string(string)
+        logger.debug "Setting #{string}"
+        logger.debug "Env is now: #{env}"
+        env
+      end
+      update_remote_environment(env)
+      default
+    end
+
+    # The `env:edit` task uses your EDITOR to load the `.env` file locally, saving any changes
+    # to all servers.
+    desc 'Edit the server environment'
+    task :edit do
+      content = edit_file environment_file
+      env = Recap::Support::Environment.from_string(content)
+      update_remote_environment(env)
+      default
+    end
+
+    # The `env:reset` tasks reverts all variables back to their default values.  If there is no default value,
+    # the variable will be removed.
+    desc 'Reset the server environment to its default values'
+    task :reset do
+      as_app "rm -f #{environment_file}", "~"
+      set
+    end
+
+    def current_environment
+      @current_environment ||= begin
+        if deployed_file_exists?(environment_file, '.')
+          Recap::Support::Environment.from_string(capture("cat #{environment_file}"))
+        else
+          Recap::Support::Environment.new
+        end
+      end
+    end
+
+    def update_remote_environment(env)
+      logger.debug "Env is now #{env}"
+
+      default_env.each do |name, value|
+        env.set(name, value) unless env.get(name)
+      end
+
+      if env.empty?
+        as_app "rm -f #{environment_file}", "~"
+      else
+        put_as_app env.to_s, environment_file
+      end
+    end
+  end
+
+  # Default environment values can be set by a recipe using `set_default_env :NAME, 'VALUE'`.
+  def set_default_env(name, value)
+    default_env[name] = value
+  end
+
+  def default_env
+    @default_env ||= {}
+  end
+
+  def env_argv
+    ARGV[1..-1]
+  end
+end

data/lib/recap/{foreman.rb → tasks/foreman.rb}

@@ -1,24 +1,28 @@
-module Recap::Foreman
-  extend Recap::Namespace
+# These tasks configure recap to use Foreman to stop, start and restart your application processes.
+
+require 'recap/tasks'
+
+module Recap::Tasks::Foreman
+  extend Recap::Support::Namespace
 
   namespace :foreman do
-    # Processes are delcared in a `Procfile`, by default in the root of the application directory
+    # Processes are declared in a `Procfile`, by default in the root of the application directory.
     set(:procfile) { "#{deploy_to}/Procfile" }
 
-    # Foreman startup scripts are exported in `upstart` format by default
+    # Foreman startup scripts are exported in `upstart` format by default.
     set(:foreman_export_format, "upstart")
 
-    # Scripts are exported (as the the application user) to a temporary location first
+    # Scripts are exported (as the the application user) to a temporary location first.
     set(:foreman_tmp_location) { "#{deploy_to}/tmp/foreman" }
 
-    # After exports, the scripts are moved to their final location, usually `/etc/init`
+    # After exports, the scripts are moved to their final location, usually `/etc/init`.
     set(:foreman_export_location, "/etc/init")
 
-    # The standard foreman export
+    # The standard foreman export.
     set(:foreman_export_command) { "./bin/foreman export #{foreman_export_format} #{foreman_tmp_location} --procfile #{procfile} --app #{application} --user #{application_user} --log #{deploy_to}/log" }
 
     namespace :export do
-      # After each deployment, the startup scripts are exported if the `Procfile` has changed
+      # After each deployment, the startup scripts are exported if the `Procfile` has changed.
       task :if_changed do
         if deployed_file_changed?(procfile)
           top.foreman.export.default
@@ -28,6 +32,7 @@ module Recap::Foreman
       # To export the scripts, they are first generated in a temporary location, then copied to their final
       # destination.  This is done because the foreman export command needs to be run as the application user,
       # while sudo is required to write to `/etc/init`.
+      desc 'Export foreman configuration'
       task :default do
         if deployed_file_exists?(procfile)
           as_app foreman_export_command
@@ -37,21 +42,24 @@ module Recap::Foreman
       end
     end
 
-    # Starts all processes that form the application
+    # Starts all processes that form the application.
+    desc 'Start all application processes'
     task :start do
       if deployed_file_exists?(procfile)
         sudo "start #{application}"
       end
     end
 
-    # Restarts all processes that form the application
+    # Restarts all processes that form the application.
+    desc 'Restart all application processes'
     task :restart do
       if deployed_file_exists?(procfile)
         sudo "restart #{application} || sudo start #{application}"
       end
     end
 
-    # Stops all processes that form the application
+    # Stops all processes that form the application.
+    desc 'Stop all application processes'
     task :stop do
       if deployed_file_exists?(procfile)
         sudo "stop #{application}"
@@ -61,4 +69,4 @@ module Recap::Foreman
     after 'deploy:update_code', 'foreman:export:if_changed'
     after 'deploy:restart', 'foreman:restart'
   end
-end
+end

data/lib/recap/{preflight.rb → tasks/preflight.rb}

@@ -17,50 +17,52 @@
 # This preflight recipe checks each of these things in turn, and attempts to give helpful advice
 # should a check fail.
 
-module Recap::Preflight
-  extend Recap::Namespace
+require 'recap/tasks'
+
+module Recap::Tasks::Preflight
+  extend Recap::Support::Namespace
 
   namespace :preflight do
-    # The preflight check is pretty quick, so run it before every `deploy:setup` and `deploy`
+    # The preflight check is pretty quick, so run it before every `deploy:setup` and `deploy`.
     before 'deploy:setup', 'preflight:check'
     before 'deploy', 'preflight:check'
 
     set(:remote_username) { capture('whoami').strip }
 
     task :check do
-      # First check the `application_user` exists
+      # First check the `application_user` exists.
       if exit_code("id #{application_user}").strip != "0"
         abort %{
-The application user '#{application_user}' doesn't exist.  You can create this user by logging into the server and running:
+The application user '#{application_user}' doesn't exist.  Did you run the `bootstrap` task?  You can also create this user by logging into the server and running:
 
     sudo useradd #{application_user}
 \n}
       end
 
-      # Then the `application_group`
+      # Then the `application_group`.
       if exit_code("id -g #{application_group}") != "0"
         abort %{
-The application group '#{application_group}' doesn't exist.  You can create this group by logging into the server and running:
+The application group '#{application_group}' doesn't exist.  Did you run the `bootstrap` task?  You can also create this group by logging into the server and running:
 
     sudo groupadd #{application_group}
     sudo usermod --append -G #{application_group} #{application_user}
 \n}
       end
 
-      # Check the git configuration exists
+      # Check the git configuration exists.
       if capture('git config user.name || true').strip.empty? || capture('git config user.email || true').strip.empty?
         abort %{
-Your remote user must have a git user.name and user.email set.  You can set these by logging into the server as #{remote_username} and running:
+Your remote user must have a git user.name and user.email set.  Did you run the `bootstrap` task?  You can also set these by logging into the server as #{remote_username} and running:
 
     git config --global user.email "you@example.com"
     git config --global user.name "Your Name"
 \n}
       end
 
-      # And finally check the remote user is a member of the `application_group`
+      # And finally check the remote user is a member of the `application_group`.
       unless capture('groups').split(" ").include?(application_group)
         abort %{
-Your remote user must be a member of the '#{application_group}' group in order to perform deployments.  You can add yourself to this group by logging into the server and running:
+Your remote user must be a member of the '#{application_group}' group in order to perform deployments.  Did you run the `bootstrap` task?  You can also add yourself to this group by logging into the server and running:
 
     sudo usermod --append -G #{application_group} #{remote_username}
 \n}

data/lib/recap/tasks/rails.rb

@@ -0,0 +1,42 @@
+# The rails tasks add to the standard deployment with tasks to support running
+# database migrations and precompiling assets.
+
+require 'recap/tasks'
+
+module Recap::Tasks::Rails
+  extend Recap::Support::Namespace
+
+  namespace :rails do
+    namespace :db do
+      task :load_schema do
+        if deployed_file_exists?("db/schema.rb")
+          as_app './bin/rake db:create db:schema:load'
+        end
+      end
+
+      task :migrate do
+        if deployed_file_changed?("db/schema.rb")
+          as_app './bin/rake db:migrate'
+        end
+      end
+    end
+
+    # The `rails:assets:precompile` runs rails' asset precompilation rake task on
+    # the server.  As assets come from so many sources (app/assets, vendor/assets
+    # and from individual gems) it's not easy to determine whether compilation is
+    # required, so it is done on every deploy.
+    namespace :assets do
+      task :precompile do
+        as_app "./bin/rake RAILS_GROUPS=assets assets:precompile"
+      end
+    end
+
+    # After the code is first cloned (during `deploy:setup`) load the schema into
+    # the database.
+    after "deploy:clone_code", "rails:db:load_schema"
+
+    # On every deploy, after the code is updated, run the database migrations
+    # and precompile the assets.
+    after "deploy:update_code", "rails:db:migrate", "rails:assets:precompile"
+  end
+end

data/lib/recap/tasks.rb

@@ -0,0 +1,16 @@
+# Recap provides a number of capistrano tasks to aid with deployment.  The core functionality
+# is found in the [tasks for deployment](tasks/deploy.html) and those for
+# [altering environment variables](tasks/env.html).
+#
+# Supporting these are [preflight checks](tasks/preflight.html) to ensure servers and
+# users are correctly setup, and the [bootstrap tasks](tasks/bootstrap.html) that help
+# do this setting up.
+#
+# In addition, there are extensions for [bundler](tasks/bundler.html),
+# [foreman](tasks/foreman.html), and [rails](tasks/rails.html) that add extra
+# functionality to the standard deploy.
+
+require 'recap'
+
+module Recap::Tasks
+end

data/lib/recap/version.rb

@@ -1,3 +1,3 @@
 module Recap
-  VERSION = "0.2.0"
+  VERSION = '1.0.0'
 end