statistrano 1.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 01c39986ca62a7822f5408c54b6a8f26895b12e4
+  data.tar.gz: f936b3560996e755990ad64a302b5c4fb63f264a
+SHA512:
+  metadata.gz: f4d57e9c63c268d9c328eb4b9d43a1d2deb9a2a7311649149d3faa3065ba438b78a5cf0eaeb9f6ee2a79cedae595658380d6c4bf13ed436febf7cd0a1a88a604
+  data.tar.gz: 7428563bae6150a2d7de3afef2392bb8ca6725f3aa9fc62a6f188960288d500a2cc2c11fb7a4e92315cc3fea8f0eda430fbaf4763d0c88df55ccbe9965728270

data/changelog.md

@@ -0,0 +1,161 @@
+# 1.2.0
+- remote specific config is now tied directly to the remote through it's own config object. Internally this cleans up many checks, but causes [BREAKING] changes if you depended on the API of any of the internal classes. If you use config data in any of your tasks, it's now suggested that you do so inside your `remotes` iterators.
+- get `Strategy::Branches` supporting multiple remotes. The stdout output of `list_releases` and `prune_releases` has changed, so if you depended on this it may be breaking.
+- move `Strategy::Branches` custom behavior to a `post_deploy_task` so it uses the same `deploy` method inherited from `Strategy::Base`. This could cause [BREAKING] changes if you use a custom `post_deploy_task` with a `Branches` deploy type.
+
+# 1.1.0
+- `#persisted_releaser` is available on a deployment from rake tasks. this will be the same for tasks called during a deploy for example.
+- addition of a `#current_release_data` method for the Revisions releaser. This pulls merged data from the manifest and the log file.
+- add `log_file_path` and `log_file_entry` to config to setup a log file for all deploys
+- [BREAKING] change interface of releasers to expect being able to pass a second argument (build data) to #create_release
+- add task hook for before the symlink in the Revisions releaser. `pre_symlink_task` gets called with |releaser, remote| in a remote loop so it's run for each.
+- add ability to create user rake tasks that have access to deployment information. see [the docs](doc/config/task-definitions.md) for more info
+
+# 1.0.2
+- make sure that Revisions#remove_untracked_revisions checks it against the "current" revision before removing it.
+
+# 1.0.1
+- add a second check to git after the build task to ensure build doesn't affect checked in files
+
+# 1.0.0
+- base includes a `deployment:build` and `deployment:post_deploy` task to allow direct triggering of these deployment steps
+- add the `verbose` option for deployments
+- fix bug in default logger to adjust for statuses that are too long
+- create `Branches::Index` and render erb for the template
+- move Branches specific ideas into the Branches namespace
+- add `Deployment::Manifest#put` method to update manifest data for matching records
+- remove `Statistrano::Deployment::Manifest` & `Statistrano::Deployment::Manifest::RemoteStore` in favor of using the same manifest as the Revisions releaser
+- add option for rsync flags [b5a248be8d96d142ca94c076d80ad6deaa0fa69e]
+- loosen rainbows dependency to work with old & new bananabin
+- reorganize deployment types & releasers. now use a single remote object, and different "strategies" for base, releases, & branches and different "releasers" for single or revisions
+- remote multi_target in favor of merging code paths w/ strategies & releasers
+- can now access deployment info directly in build_tasks & post_deploy_tasks by giving arity [de05bb3a7d760fc51571b0f93f457065758fa772]
+- rake tasks no manually registered (instead of on initialization) [ac72eb0a65681e472b21c486fa67f7f0dd635c02]
+- add explicit setting for file & directory permissions on deploy [25ed930235e348fd6068cedbdc09b33e788fc3d5]
+
+# 0.10.0
+- tag release
+
+# 0.10.0.rc3
+- fix copy current release step, target needs to not exist
+
+# 0.10.0.rc2
+- copy current release to help reduce time spent rsyncing new build
+
+# 0.10.0.rc1
+- make dir with 775, so global (ngnx) can read them
+
+# 0.10.0.beta3
+- release dir created recursively, ensures permissions on releases dir
+- add guard to not remove a currently symlinked release
+
+# 0.10.0.beta2
+- manifests check if they exist before trying to create themselves
+- add Target#test_connection method to allow for early testing of remote connections
+- MultiTarget post_deploy_task accepts blocks just like build_task
+- add a "verbose" option to Target to log each command run
+
+# 0.10.0.beta1
+- add a "new architecture" MultiTarget deployment type
+- fix Util::symbolize_hash_keys to work with nested hashes
+- add a types cache and register methods for registering deployment types
+- remove Git code (it wasn't being used)
+
+# 0.9.1
+- bump Asgit dependency to 0.1
+
+# 0.9.0
+- misc refactoring
+- switch to Asgit for git status queries
+- change the way ssh sessions are handled, now passed with the config
+- using HereOrThere for running commands (has a consistent response object)
+
+# 0.8.1
+- fix nil error for manifest in branches
+
+# 0.8.0
+- re-architect configuration for deployment classes
+- now suport a "sugar" dsl syntax for setting config while defining deployments
+
+# 0.7.2
+- fix bug where branch deployments would update timestamp on all branches in the manifest
+
+# 0.7.1
+- add an `open` rake task for Branches deployments to navigate to the url
+
+# 0.7.0
+- big refactoring to reduce complexity of the public methods
+
+# 0.6.1
+- fix a regression that caused Git.remote_up_to_date? to fail
+
+# 0.6.0
+- move a few setup methods
+- add integration specs for the deployment modules
+- add a spec for the git module
+- rewrite Shell.run to use Open3 and improve output
+
+# 0.5.3
+- loosen all the dependencies
+
+# 0.5.2
+- loosen dependency on slugity
+
+# 0.5.1
+- add environment variable DEPLOYMENT_ENVIRONMENT set to the name of the deployment
+
+# 0.5.0
+- only create a single ssh connection for the deploy task (after_deploy creates a second)
+- add exception handling to `invoke_build_task`, exit and log on an exception
+
+# 0.4.1
+- expose less of the statistrano namespace to help with conflicts of common names (like Log)
+
+# 0.4.0
+- now abort on errors
+
+# 0.3.1
+- add rake task descriptions
+- add times for rsync task
+
+# 0.3.0
+- change rsync behavior, adds delete-after
+- clone previous release first if it exits for release type deployments
+
+# 0.2.2
+- move setup to a `prepare_for_action` method, defer connection until needed
+
+# 0.2.1
+- regenerate index after pruning releases
+
+# 0.2.0
+- code overhaul
+- new way to define deployments
+- classes for different deployment types
+- add pruning to branches deployments
+
+# 0.1.3
+- fix error with newlines in the current_git_commit
+
+# 0.1.2
+- updated apearance of index page
+
+# 0.1.1
+- add updated at to feature index page
+
+# 0.1.0
+- add post_deploy_task to servers
+- add generate namespace, and generate:index task to rake tasks
+
+# 0.0.4
+- fix log order bug, standardize the printed output
+
+# 0.0.3
+- fixed bug with manifest for releases that have the same name
+
+# 0.0.2
+- fix manifest creation for feature releases
+- add a releases:browse task
+
+# 0.0.1
+- initial gem creation

data/doc/config/file-permissions.md

@@ -0,0 +1,33 @@
+---
+title: File Permissions
+---
+
+In some cases you may be deploying into an environment where the default chmod settings of 755 for directories and 644 for files isn't appropriate. Lucky for you, there's a setting for that :).
+
+For example if we'd like to deploy to a server using different users that are part of the same group:
+
+```ruby
+define_deployment "example" do
+
+  # set the permissions directories will be
+  # created with
+  dir_permissions 775
+
+  # set the permissions files will be
+  # created with
+  file_permissions 664
+
+end
+```
+
+Using `775` and `664` is ok if the deployment members are part of the same group, but unless you're using the `releases` deployment strategy you'll run into trouble when rsync tries to update the timestamps on directories. You *must* be the owner of the directory to do that. Getting around that little caveat we can configure the rsync flags to skip updating timestamps:
+
+```ruby
+define_deployment "example" do
+
+  rsync_flags "-aqz " + # archive, quiet, & compress
+              "-O "   + # omit timestamp updates from directories
+              "--delete-after" # remove orphaned files *after* the sync is complete
+
+end
+```

data/doc/config/log-files.md

@@ -0,0 +1,32 @@
+---
+title: Log Files
+---
+
+You can specify a log file to store a record of every deploy. These logs could eventually get pretty large, so it's suggested you point logrotate at the log files to keep them in check.
+
+The data that is stored for each release is completely up to you, and definable with the `log_file_content` method. It will accept an argument for the `deployment`, `releaser`, `build_data`, and `post_deploy_data` and expects a hash to be returned (or an object with to_json).
+
+Here we'll use [Asgit](https://github.com/stevenosloan/asgit) to create a model of our projects repo urls. Lets pretend our project is called `caesar` on github.
+
+```ruby
+
+repo = Asgit::Project.new service:        :github,
+                          organization:   'mailchimp',
+                          project:        'caesar',
+                          default_branch: 'master'
+
+
+define_deployment "caesar" do
+
+  log_file_path "/var/log/caesar.deploy.log"
+  log_file_entry do |deployment, releaser, build_data, post_deploy_data|
+    {
+      time:     releaser.release_name,
+      deployer: `whoami`,
+      commit:   Asgit.current_commit,
+      diff_url: repo.urls.compare( Asgit.current_commit,
+                                   deployment.log_file.last_entry[:commit] )
+    }.merge(build_data)
+  end
+
+end

data/doc/config/task-definitions.md

@@ -0,0 +1,88 @@
+---
+title: Task Definitions
+---
+
+These are the `build_task` and `post_deploy_task` setup in a deployment's config. They are flexible allowing you to set them as a block or a string to call a rake task.
+
+You can also create your own tasks that have access to the Statistrano deployment & remotes.
+
+
+### Call a Rake Task
+
+```ruby
+define_deployment "example" do
+
+  build_task "base:build"
+  # this will call `Rake::Task['base:build'].invoke`
+
+end
+```
+
+
+### Run a Block
+
+Without any need for deployment context:
+
+```ruby
+define_deployment "example" do
+
+  build_task do
+    # run our block of code
+    BuildScript("example")
+    # => { foo: "bar", wu: "tang" }
+
+    # if we return a hash, depending on the deployment
+    # strategy it may use that build metadata
+  end
+
+end
+```
+
+If we need the deployment object for context:
+
+```ruby
+define_deployment "example" do
+
+  build_task do |deployment|
+    # by giving the task arity we can access the
+    # deployment object
+
+    deployment.name
+    # => example
+  end
+
+end
+```
+
+### Define Your Own Tasks
+
+For this we have two methods usable in the configuration blog, `namespace` and `task`.
+
+`namespace` wraps any tasks (or other namespaces) you define to allow creating a sane structure to your new tasks.
+
+`task` creates a new task with name & description. Like the `build_task` and `post_deploy_task` if you give your block arity you'll be able to access the deployment.
+
+An example:
+```ruby
+example = define_deployment "example" do
+  task :test_connections, 'test connection to the remotes' do |deployment|
+    deployment.remotes.each(&:test_connection)
+  end
+
+  namespace :php do
+    task :restart, 'restart php-fpm on each remote' do |deployment|
+      deployment.remotes.each do |r|
+        r.run "sudo php-fpm restart"
+      end
+    end
+  end
+end
+example.register_tasks
+```
+
+This will give you tasks that look like this:
+```bash
+$ rake -T
+example:test_connections  # test connection to the remotes
+example:php:restart       # restart php-fpm on each remote
+```

data/doc/getting-started.md

@@ -0,0 +1,96 @@
+---
+title: Getting Started
+---
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "statistrano", git: "git@github.com:mailchimp/statistrano.git",
+                   tag: "1.0.0"
+```
+
+Bundle:
+
+```bash
+$ bundle install
+```
+
+
+## Setting up a deployment
+
+In a Rakefile (typically `tasks/deploy.rake`) we'll require statistrano then define an example deployment.
+
+```ruby
+# tasks/deploy.rake
+require 'statistrano'
+
+example = define_deployment "example", :base do
+
+  # first we setup the host we deploy to,
+  # we will have set this up in ~/.ssh/config so we
+  # can ssh to it using a pubkey as auth
+  hostname 'digitalocean'
+
+  # now we'll configure the source and target directories
+  local_dir  'build'
+  remote_dir '/opt/example'
+
+  # we have access to two task hooks, the build_task
+  # and the post_deploy_task. they can work in two different ways:
+  #   1. if given a string, they call a rake task
+  #   2. if given a block they run that block when called,
+  #      see the build task guide for more information
+  #
+  # in this case we'll run the block
+  build_task do |deployment|
+    # it's good to check if your connections are all valid
+    deployment.remotes.each(&:test_connection)
+
+    ENV['BUILD_ENV'] = "example"
+    Rake::Task['middleman:build'].invoke
+  end
+  # and just call the rake task here
+  post_deploy_task 'middleman:cleanup'
+
+  # statistrano can guard agains errant deploys that aren't
+  # checked into version control. we just have to give it the
+  # branch we want to check against
+  check_git  true
+  git_branch 'master'
+
+  # there is support for deploying to multiple remotes
+  # simultaniously, any config option can be overriden for an
+  # individual remote in it's option hash
+  remotes [
+    { hostname: 'remote01', remote_dir: '/var/www/mailchimp01' },
+    { hostname: 'remote02', remote_dir: '/var/www/mailchimp02' }
+  ]
+end
+```
+
+We don't have any rake tasks set up now though, as they aren't registered by default. Calling the `register_tasks` method on the deployment will set up the default ones.
+
+```ruby
+example.register_tasks
+```
+
+Though in some cases you may want to skip that and register them manually (like if you need to set specific env variables).
+
+Now to deploy you'd run `rake example:deploy`.
+
+For more information on specific, check out the guides below.
+
+## Strategies
+
+- [Base](/doc/strategies/base.md)
+- [Revisions](/doc/strategies/revisions.md)
+- [Branches](/doc/strategies/branches.md)
+
+
+## Configuration
+
+- [Task Definitions](/doc/config/task-definitions.md)
+- [File Permissions](/doc/config/file-permissions.md)
+- [Log Files](/doc/config/log-files.md)

data/doc/strategies/base.md

@@ -0,0 +1,38 @@
+---
+title: Base Strategy
+---
+
+As it's name would imply, the `base` strategy is just that, a base. Each of the other strategies build off of it, that doesn't mean it's not useful though. It can still move your code to a target location on multiple remotes.
+
+This strategy will take the contents of the defined `local_dir` and sync them to the `remote_dir` on your remotes.
+
+### Example:
+
+```ruby
+# tasks/deploy.rake
+require 'statistrano'
+
+example = define_deployment "example", :base do
+
+  hostname 'digitalocean'
+
+  local_dir  'build'
+  remote_dir '/opt/example'
+
+  build_task do |deployment|
+    deployment.remotes.each(&:test_connection)
+    Rake::Task['middleman:build'].invoke
+  end
+
+  post_deploy_task 'middleman:cleanup'
+
+  check_git  true
+  git_branch 'master'
+
+  remotes [
+    { hostname: 'remote01', remote_dir: '/var/www/mailchimp01' },
+    { hostname: 'remote02', remote_dir: '/var/www/mailchimp02' }
+  ]
+
+end
+```

data/doc/strategies/branches.md

@@ -0,0 +1,82 @@
+---
+title: Branches Strategy
+---
+
+Inspired by layervault's [Divergence](http://cosmos.layervault.com/divergence.html), the Branches strategy is special built for staging all the things. It will do a base deploy to a subdirectory based on the current git branch, then generate and index w/ all of the currently staged branches. With the correct bit of nginx (or apache) setup each branch is accessible from a subdomain.
+
+### Example
+
+```ruby
+deployment = define_deployment "branches", :branches do
+
+  # in addition to the "base" options
+
+  # the allow the generated index properly create links to the
+  # subdomains, we need to give it a base to work off of
+  base_domain "mailchimp.com"
+
+  # the public_dir is the subdir under remote_dir where the site
+  # will be deployed, for branch based locations *don't* touch this
+  # but if we want to mount a different project we can manually manipulate this
+  public_dir  "current_branch"
+
+  # the post deploy task defaults to generating the index file
+  # and adding the current_release to the manifest
+  # so if you touch this keep that in mind as you may want to
+  # generate that as well
+  post_deploy_task do |deployment|
+    d.push_current_release_to_manifest
+    d.generate_index
+  end
+
+end
+```
+
+Like base deployments, we need to register the rake tasks if we'd like the defaults to be available.
+
+```ruby
+deployment.register_tasks
+```
+
+`rake branches:deploy`  
+deploys local_dir to the remote named for the current git branch, and generates an index page
+
+`rake branches:list`  
+lists all the currently deployed branches
+
+`rake branches:open`  
+If you have set a base_domain, opens the branch in your default browser
+
+`rake branches:prune`  
+shows list of currently deployed branches to pick from and remove
+
+`rake branches:generate_index`  
+manually kicks of index generation, typically you shouldn't need to do this
+
+
+### NGINX configs
+
+Set up your configs to pass the subdomain down as the docroots, here's some relavent configs:
+
+```nginx
+server {
+  listen 80;
+  server_name ~^(?<subdomain>.*)\.yourdomain.com;
+
+  # use the subdomain captured above in the docroot
+  root /var/www/branches.yourdomain.com/$subdomain;
+  index index.html index.htm index.php;
+
+  # pass the subdomain to fastcgi as well
+  location ~ \.php$ {
+      #fastcgi_pass 127.0.0.1:9000;
+      # With php5-fpm:
+      fastcgi_pass unix:/var/run/php5-fpm.sock;
+      fastcgi_index index.php;
+      include fastcgi_params;
+      fastcgi_param SCRIPT_FILENAME /var/www/branches.yourdomain.com/$subdomain$fastcgi_script_name;
+  }
+
+  # other nginx stuf ..
+}
+```

data/doc/strategies/releases.md

@@ -0,0 +1,110 @@
+---
+title: Releases Strategy
+---
+
+The Releases strategy is really made for production environments. If you are familiar with the way [Capistrano](https://github.com/capistrano/capistrano) works, it is very similar. Deploys work by creating a new "release" directory with fresh code, then symlinking that to the "current" directory. It's a little different from Capistrano in that it doesn't really care about the remote environment, it just runs the commands you give it.
+
+Did you botch a release? No big deal™. You can rollback to the previous state while you fix the mistake. This strategy also provides a facility for storing a little bit of metadata about each release. (more on that later).
+
+### Example:
+
+```ruby
+# tasks/deploy.rake
+require 'statistrano'
+
+deployment = define_deployment "production", :releases do
+
+  # in addition to the "base" config options, there
+  # are some (all defaulted) options specific for releases
+
+  # the release_count defines how many releases to store in
+  # history, more releases gives you more history to rollback
+  # but takes up more space
+  release_count 5
+
+  # each release creates it's own directory inside the
+  # release_dir so it's full path would be:
+  # /#{remote_dir}/releases/#{release_number}
+  release_dir  "releases"
+
+  # combined with the `remote_dir`, `public_dir` defines the
+  # the directory that gets symlinked to, point your docroot here:
+  # #{remote_dir}/#{public_dir}
+  public_dir   "current"
+
+  # allows a task to run before the symlink gets updated
+  # you might use this to run tests on the target servers
+  #
+  # if you return false or raise an exception, the deploy
+  # will cease, leaving the rsynced directories for inspection.
+  # it is suggested that you log an error with an explaination
+  #
+  # unlike other tasks, this is called in the remotes loop
+  # so is run for each remote
+  pre_symlink_task do |releaser, remote|
+    release_path = File.join remote.config.remote_dir, remote.config.release_dir, releaser.release_name
+    unless remote.run("#{release_path}/bin/test_something").success?
+      Statistrano::Log.error :"#{remote.config.hostname}", "failed to pass test"
+      false # returning false stops the deploy
+    else
+      true
+    end
+  end
+
+end
+```
+
+Like base deployments, we need to register the rake tasks if we'd like the defaults to be available.
+
+```ruby
+deployment.register_tasks
+```
+
+In addition to `deploy` we get a few more utilities for managing releases.
+
+`rake production:rollback`  
+rolls back to the previous release.
+
+`rake production:prune`  
+manually removes old releases beyond the release count
+
+`rake production:list`  
+lists all the currently deployed releases
+
+
+### Build Metadata
+
+Releases are managed using a manifest on the remote, and there is a facility to add more data to this manifest for each release. If your build_task returns a hash, it will be merged in to be stored with the release.
+
+```ruby
+define_deployment "production", :releases do
+
+  # other config ...
+
+  build_task do
+    BuildScript("production")
+    # => { time: 60, css: "145kb", whoami: 'freddie' }
+  end
+
+  # now on deploy, along with the release name,
+  # the time, css, and whoami keys will be stored
+
+end
+```
+
+### With PHP
+
+PHP has [been known to have problems](http://stackoverflow.com/questions/18450076/capistrano-symlinks-being-cached) updating to newer symlinks. So it's a good idea to "kick the tires" in a `post_deploy_task` if this may be a problem for you. In this case, reloading php with fpm.
+
+```ruby
+define_deployment "production", :releases do
+
+  post_deploy_task do |deployment|
+    deployment.remotes.each do |remote|
+      remote.run "service php-fpm reload"
+    end
+  end
+
+  # other config...
+end
+```

data/doc/strategies.md

@@ -0,0 +1,17 @@
+---
+title: Strategies
+---
+
+Give the strategy as the second argument to `define_deployment`. For example to use a `releases` strategy:
+
+```ruby
+define_deployment "example", :releases do
+  # configuration
+end
+```
+
+For more specifics about each strategy:
+
+- [Base](/doc/strategies/base.md)
+- [Releases](/doc/strategies/releases.md)
+- [Branches](/doc/strategies/branches.md)