statistrano 1.2.0

data/readme.md

@@ -0,0 +1,247 @@
+Description
+===========
+
+A gem to simplify the deployment of static sites, and staging of feature branches.
+
+
+
+Installation
+============
+
+With Bundler
+```ruby
+gem "statistrano", git: "git@github.com:mailchimp/statistrano.git",
+                   tag: "X.X.X"
+```
+
+
+Examples
+========
+
+### Base deployment
+
+The base setup simply copies a local directory to a remote directory
+
+```ruby
+# deploy.rake
+require 'statistrano'
+
+deployment = define_deployment "basic" do
+
+  hostname   'remote_name'
+  user       'freddie' # optional if remote is setup in .ssh/config
+  password   'something long and stuff' # optional if remote is setup in .ssh/config
+
+  remote_dir '/var/www/mailchimp.com'
+  local_dir  'build'
+  build_task 'middleman:build' # optional if nothing needs to be built
+  post_deploy_task 'base:post_deploy' # optional if no task should be run after deploy
+
+  dir_permissions  755 # optional, the perms set on rsync & setup for directories
+  file_permissions 644 # optional, the perms set on rsync & setup for files
+  rsync_flags      '-aqz --delete-after' # optional, flags for rsync
+
+  check_git  true # optional, set to false if git shouldn't be checked
+  git_branch 'master' # which branch to check against
+
+  # optional, you can define multiple remotes to deploy to
+  # any config option can be overriden in the remote's data hash
+  remotes [
+    { hostname: 'remote01', remote_dir: '/var/www/mailchimp01' },
+    { hostname: 'remote02', remote_dir: '/var/www/mailchimp02' }
+  ]
+
+end
+```
+
+**Rake Tasks**
+
+Once a deployment is defined, you can register it's tasks -- or call the methods directly.
+
+```ruby
+# deploy.rake
+deployment.register_tasks
+# => rake tasks are registered
+```
+
+`rake basic:deploy`  
+deploys the local_dir to the remote_dir. optionally call `deployment.deploy`
+
+
+### Releases deployment
+
+Out of the box Statistrano allows you to pick from a release based deployment, or branch based. Releases act as a series of snapshots of your project with the most recent linked to the `public_dir`. You can quickly rollback in case of errors.
+
+```ruby
+# 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
+  release_count 5
+  release_dir  "releases"
+  public_dir   "current"
+
+end
+```
+
+**Rake Tasks**
+
+Once a deployment is defined, you can register it's tasks -- or call the methods directly.
+
+```ruby
+# deploy.rake
+deployment.register_tasks
+# => rake tasks are registered
+```
+
+`rake production:deploy`  
+deploys local_dir to the remote, and symlinks remote_dir/current to the release.
+
+`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
+
+
+### Branch deployment
+
+The branch deployment type adds some nice defaults to use the current branch as your release name. So with the correct nginx/apache config you can have your branches mounted as subdomains (eg: `http://my_awesome_branch.example.com`). Aditionally it is set up to create an `index` release that shows a list of your currently deployed branches.
+
+
+```ruby
+deployment = define_deployment "branches", :branches do
+
+  # in addition to the "base" options
+  base_domain "mailchimp.com" # used to generate the subdomain links in the index file
+  public_dir  "current_branch" # defaults to a slugged version of the current branch
+  post_deploy_task "name:generate_index" # defaults to create the index file
+
+end
+```
+
+**Rake Tasks**
+
+Once a deployment is defined, you can register it's tasks -- or call the methods directly.
+
+```ruby
+# deploy.rake
+deployment.register_tasks
+# => rake tasks are registered
+```
+
+`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
+
+
+## Build & Post Deploy Tasks
+
+Of note, the `build_task` & `post_deploy_task` can be defined as a block. Some release types (like "releases") will use a hash if it is returned by the block.
+
+```ruby
+deployment = define_deployment 'multi', :releases do
+  build_task do
+    Rake::Task['build'].invoke
+    { commit: Asgit.current_commit }
+  end
+end
+
+deployment.deploy
+# => remote/manifest.manifest will end up with [{release: 'timestamp', commit: 'commit_sha'}]
+```
+
+You can also access the current deployment info by giving the block arity.
+
+```ruby
+deployment = define_deployment 'multi', :releases do
+  build_task do |dep|
+    puts dep.name
+  end
+end
+
+deployment.invoke_build_task
+# => will output the deployment name 'multi'
+```
+
+### Config Syntax
+
+In addition to the "DSL" way of configuring, the `define_deployment` block will yield the config if an argument is passed. You can use this if you need to do any specific manipulation to config (is also the "old" syntax).
+
+```ruby
+define_deployment "basic" do |config|
+
+  config.remote     =  'remote_name'
+  config.remote_dir =  '/var/www/mailchimp.com'
+  config.local_dir  =  'build'
+
+end
+```
+
+
+Testing
+=======
+
+Tests are written in rspec, and can be run with `rspec`. To run an individual test, run `rspec path/to/spec.rb`.
+
+Integraton tests run through `localhost`, this requires that you setup ssh through localhost to run the tests. Look at [setup](#setup) for help with that.
+
+
+### Setup
+
+On Mac OS X 10.8, you should enable remote login.
+
+```
+System Preferences -> Sharing -> Turn on Remote Login
+```
+
+And setup your `.ssh/config`
+
+```
+Host localhost
+  HostName localhost
+  User {{your_username}}
+```
+
+Then add your pub key to `.ssh/authorized_keys`.
+
+Depending on how you've setup your `.bashrc` is setup, you may need to move any PATH manipulation to the front of the file to prevent commands from failing.
+
+
+### Test accross multiple rubies
+
+To run specs accross the supported rubies, run `bin/multi_ruby_rspec`
+
+
+Contributing
+============
+
+If there is any thing you'd like to contribute or fix, please:
+
+- Fork the repo
+- Add tests for any new functionality
+- Make your changes
+- Verify all existing tests work properly
+- Make a pull request
+
+
+License
+=======
+The statistrano gem is distributed under the MIT License.

data/spec/integration_tests/base_integration_spec.rb

@@ -0,0 +1,103 @@
+require 'spec_helper'
+
+describe "Statistrano::Deployment::Base integration", :integration do
+
+  after :each do
+    reenable_rake_tasks
+    Given.cleanup!
+  end
+
+  context "with a single remote" do
+    it "deploys the contents of source to the 'deploy' folder" do
+      Given.fixture "base"
+      base = define_deployment "base" do |c|
+        c.build_task = 'remote:copy'
+        c.hostname   = 'localhost'
+        c.local_dir  = 'build'
+        c.remote_dir = File.join( Dir.pwd, 'deployment' )
+      end
+
+      base.deploy
+      result_a = Statistrano::Shell.run_local("ls source")
+      result_b = Statistrano::Shell.run_local("ls deployment")
+
+      expect( result_a ).to be_success
+      expect( result_b ).to be_success
+      expect( result_a.stdout ).to eq result_b.stdout
+    end
+
+    it "doesn't create a deployment on the remote & should return false if there is a build error" do
+      Given.fixture "error_on_build"
+      expect( Statistrano::Shell.run_local("rake error:deploy") ).not_to be_success #confirming the error
+
+      expect( Dir.exists?("deployment") ).to be_falsy
+    end
+
+    it "appends to a log file with each deploy" do
+      Given.fixture "base"
+      deploys = 0
+      base = define_deployment "base" do
+        build_task 'remote:copy'
+        hostname   'localhost'
+        local_dir  'build'
+        remote_dir File.join( Dir.pwd, 'deployment' )
+
+        log_file_path File.join( Dir.pwd, 'deploy.log' )
+        log_file_entry do |d, r, b_d, p_d_d|
+          { deployment: (deploys += 1) }
+        end
+      end
+
+      base.deploy
+      base.deploy
+
+      expect( Statistrano::Shell.run_local("cat deploy.log").stdout ).to eq "{\"deployment\":1}\n{\"deployment\":2}\n"
+    end
+  end
+
+  context "with multiple remotes" do
+    it "deploys the contents of source to each remote" do
+      Given.fixture "base"
+      base = define_deployment "base" do
+        build_task "remote:copy"
+        hostname   "localhost"
+        local_dir  "build"
+        remote_dir File.join( Dir.pwd, 'deployment' )
+
+        remotes [
+          { remote_dir: File.join( Dir.pwd, "deployment", "target01" ) },
+          { remote_dir: File.join( Dir.pwd, "deployment", "target02" ) }
+        ]
+      end
+
+      base.deploy
+
+      expect( deployment_folder_contents ).to match_array [ "target01", "target02" ]
+    end
+  end
+
+  context "with specific file permissions" do
+    it "deploys with those permissions" do
+      Given.fixture "base"
+      base = define_deployment "base" do
+        build_task "remote:copy"
+        hostname   "localhost"
+        local_dir  "build"
+        remote_dir File.join( Dir.pwd, 'deployment' )
+
+        # these are really bad perms on purpose
+        dir_permissions 777
+        file_permissions 666
+      end
+
+      base.deploy
+
+      deployment_dir_perms  = sprintf( "%o", File.stat("deployment").mode ).chars.to_a.last(3).join
+      deployment_file_perms = sprintf( "%o", File.stat("deployment/index.html").mode ).chars.to_a.last(3).join
+
+      expect( deployment_dir_perms ).to eq "777"
+      expect( deployment_file_perms ).to eq "666"
+    end
+  end
+
+end

data/spec/integration_tests/branches_integration_spec.rb

@@ -0,0 +1,189 @@
+require 'spec_helper'
+
+describe "Statistrano::Deployment::Branches integration", :integration do
+
+  context "with a single remote" do
+    before :all do
+      Given.fixture "base"
+
+      RSpec::Mocks.with_temporary_scope do
+        @deployment = define_deployment "branches", :branches do |c|
+          c.build_task  = 'remote:copy'
+          c.hostname    = 'localhost'
+          c.local_dir   = 'build'
+          c.remote_dir  = File.join( Dir.pwd, 'deployment' )
+          c.base_domain = "example.com"
+        end
+
+        allow( Asgit ).to receive(:current_branch)
+                      .and_return('first_branch')
+        allow( Time ).to receive(:now)
+                     .and_return(1372020000)
+        @deployment.deploy
+
+        allow( Asgit ).to receive(:current_branch)
+                      .and_return('second_branch')
+        allow( Time ).to receive(:now)
+                     .and_return(1372030000)
+        @deployment.deploy
+      end
+    end
+
+    after :each do
+      reenable_rake_tasks
+    end
+
+    after :all do
+      Given.cleanup!
+    end
+
+    it "generates a release at the specified branches" do
+      ["first_branch", "index", "second_branch"].each do |dir|
+        expect( deployment_folder_contents ).to include dir
+      end
+    end
+
+    it "lists the deployed branches" do
+      output = catch_stdout {
+        @deployment.list_releases
+      }
+      expect( output ).to include "first_branch"
+      expect( output ).to include "second_branch"
+    end
+
+    it "generates an index page with the correct order of branches" do
+      index_html = IO.read("deployment/index/index.html")
+      expect( index_html ).to include <<-eof
+        <li>
+          <a href="http://second_branch.example.com">second_branch</a>
+          <small>updated: Sunday Jun 23, 2013 at  7:26 pm</small>
+        </li>
+      
+        <li>
+          <a href="http://first_branch.example.com">first_branch</a>
+          <small>updated: Sunday Jun 23, 2013 at  4:40 pm</small>
+        </li>
+eof
+    end
+
+    it "removes the selected branch to prune" do
+      release_stdin 1 do
+        @deployment.prune_releases
+        expect( Dir[ "deployment/**" ] ).not_to include "deployment/first_branch"
+      end
+    end
+  end
+
+  context "with multiple remotes" do
+    before :all do
+      Given.fixture "base"
+
+      RSpec::Mocks.with_temporary_scope do
+        @deployment = define_deployment "branches", :branches do
+          build_task  'remote:copy'
+          hostname    'localhost'
+          local_dir   'build'
+          base_domain "example.com"
+          remote_dir  File.join( Dir.pwd, 'deployment' )
+
+          remotes [
+            { remote_dir: File.join( Dir.pwd, 'deployment', 'remote01' ) },
+            { remote_dir: File.join( Dir.pwd, 'deployment', 'remote02' ) }
+          ]
+        end
+
+        allow( Asgit ).to receive(:current_branch)
+                      .and_return('first_branch')
+        allow( Time ).to receive(:now)
+                     .and_return(1372020000)
+        @deployment.deploy
+
+        allow( Asgit ).to receive(:current_branch)
+                      .and_return('second_branch')
+        allow( Time ).to receive(:now)
+                     .and_return(1372030000)
+        @deployment.deploy
+      end
+    end
+
+    after :each do
+      reenable_rake_tasks
+    end
+
+    after :all do
+      Given.cleanup!
+    end
+
+    def deployment_dir_contents
+      Dir[ "deployment/**/*" ].map do |e|
+        e.sub /^deployment\/?/, ''
+      end
+    end
+
+    it "creates a release on each remote" do
+      expect( deployment_dir_contents ).to match_array [
+        "remote01",
+        "remote01/index",
+        "remote01/index/index.html",
+        "remote01/first_branch",
+        "remote01/first_branch/index.html",
+        "remote01/second_branch",
+        "remote01/second_branch/index.html",
+        "remote01/manifest.json",
+
+        "remote02",
+        "remote02/index",
+        "remote02/index/index.html",
+        "remote02/first_branch",
+        "remote02/first_branch/index.html",
+        "remote02/second_branch",
+        "remote02/second_branch/index.html",
+        "remote02/manifest.json"
+      ]
+    end
+
+    it "lists the deployed branches" do
+      @deployment.list_releases
+      output = catch_stdout {
+        @deployment.list_releases
+      }
+      expect( output ).to include "first_branch"
+      expect( output ).to include "second_branch"
+    end
+
+    it "generates an index page with the correct order of branches" do
+      expected_html = <<-eof
+        <li>
+          <a href="http://second_branch.example.com">second_branch</a>
+          <small>updated: Sunday Jun 23, 2013 at  7:26 pm</small>
+        </li>
+      
+        <li>
+          <a href="http://first_branch.example.com">first_branch</a>
+          <small>updated: Sunday Jun 23, 2013 at  4:40 pm</small>
+        </li>
+eof
+
+      expect( IO.read("deployment/remote01/index/index.html") ).to include expected_html
+      expect( IO.read("deployment/remote02/index/index.html") ).to include expected_html
+    end
+
+    it "removes the selected branch to prune" do
+      # verify deployments are there to begin with
+      expect( deployment_dir_contents ).to include "remote01/first_branch"
+      expect( deployment_dir_contents ).to include "remote02/first_branch"
+
+      release_stdin 1 do
+        @deployment.prune_releases
+      end
+
+      expect( deployment_dir_contents ).not_to include "remote01/first_branch"
+      expect( deployment_dir_contents ).not_to include "remote02/first_branch"
+
+      # verify the one we didn't remove is still there
+      expect( deployment_dir_contents ).to include "remote01/second_branch"
+      expect( deployment_dir_contents ).to include "remote02/second_branch"
+    end
+  end
+
+end

data/spec/integration_tests/releases/deploy_integration_spec.rb

@@ -0,0 +1,116 @@
+require 'spec_helper'
+
+describe "Statistrano::Deployment::Strategy::Releases#deploy integration", :integration do
+
+  context "with a single target" do
+    before :each do
+      reenable_rake_tasks
+      Given.fixture "base"
+      @subject = define_deployment "single_target", :releases do
+        build_task "remote:copy"
+        local_dir  "build"
+        remote_dir File.join( Dir.pwd, "deployment" )
+
+        release_count 2
+        remotes [{ hostname: 'localhost', verbose: true }]
+      end
+
+      allow( Time ).to receive(:now).and_return(1372020000)
+      @subject.deploy
+
+      allow( Time ).to receive(:now).and_return(1372030000)
+      @subject.deploy
+
+      allow( Time ).to receive(:now).and_return(1372040000)
+      @subject.deploy
+    end
+
+    after :each do
+      Given.cleanup!
+    end
+
+    it "generates a release with the correct time stamp,\n" +
+       "restricts the release count to the defined number,\n" +
+       "& symlinks the pub_dir to the most recent release" do
+      expect( release_folder_contents ).to match_array ["1372030000", "1372040000"]
+      expect( release_folder_contents.length ).to eq 2
+      resp = Statistrano::Shell.run_local("ls -l deployment")
+      expect( resp.stdout ).to match /current\s->(.+)\/deployment\/releases\/1372040000/
+    end
+
+    context "when pre_symlink_task fails" do
+      it "leaves the release inplace, but unlinked" do
+        @subject = define_deployment "single_target", :releases do
+          build_task "remote:copy"
+          local_dir  "build"
+          remote_dir File.join( Dir.pwd, "deployment" )
+
+          release_count 2
+          remotes [{ hostname: 'localhost', verbose: true }]
+          pre_symlink_task do
+            false
+          end
+        end
+
+        allow( Time ).to receive(:now).and_return(1372050000)
+
+        expect {
+          @subject.deploy
+        }.to raise_error SystemExit
+
+        expect( release_folder_contents ).to match_array ["1372030000", "1372040000", "1372050000"]
+        resp = Statistrano::Shell.run_local("ls -l deployment")
+        expect( resp.stdout ).to match /current\s->(.+)\/deployment\/releases\/1372040000/
+      end
+    end
+  end
+
+  context "with multiple remotes" do
+
+    before :each do
+      reenable_rake_tasks
+      Given.fixture "base"
+      subject = define_deployment "multi_target", :releases do
+        build_task "remote:copy"
+        local_dir  "build"
+        hostname   "localhost"
+        remote_dir File.join( Dir.pwd, "deployment" )
+
+        release_count 2
+        remotes [
+          { remote_dir: File.join( Dir.pwd, "deployment", "target01" ) },
+          { remote_dir: File.join( Dir.pwd, "deployment", "target02" ) },
+          { remote_dir: File.join( Dir.pwd, "deployment", "target03" ) }
+        ]
+      end
+
+      allow( Time ).to receive(:now).and_return(1372020000)
+      subject.deploy
+
+      allow( Time ).to receive(:now).and_return(1372030000)
+      subject.deploy
+
+      allow( Time ).to receive(:now).and_return(1372040000)
+      subject.deploy
+    end
+
+    after :each do
+      Given.cleanup!
+    end
+
+    it "generates a release with the correct time stamp,\n" +
+       "restricts the release count to the defined number,\n" +
+       "& symlinks the pub_dir to the most recent release" do
+      expect( multi_release_folder_contents )
+        .to match_array [ "target01/releases/1372030000", "target01/releases/1372040000",
+                          "target02/releases/1372030000", "target02/releases/1372040000",
+                          "target03/releases/1372030000", "target03/releases/1372040000" ]
+
+      ["target01","target02","target03"].each do |target|
+        resp = Statistrano::Shell.run_local("ls -l deployment/#{target}")
+        expect( resp.stdout ).to match /current\s->(.+)\/deployment\/#{target}\/releases\/1372040000/
+      end
+    end
+  end
+
+end

data/spec/integration_tests/releases/list_releases_integration_spec.rb

@@ -0,0 +1,38 @@
+require 'spec_helper'
+
+describe "Statistrano::Deployment::Strategy::Releases#list_releases integration", :integration do
+
+  context "with multiple_targets target" do
+
+    before :each do
+      Given.fixture "releases-deployed"
+      @subject = define_deployment "releases", :releases do
+        build_task "remote:copy"
+        local_dir  "build"
+        hostname   "localhost"
+        remote_dir File.join( Dir.pwd, "deployment" )
+
+        release_count 2
+        remotes [
+          { remote_dir: File.join( Dir.pwd, "deployment", "target01" ) },
+          { remote_dir: File.join( Dir.pwd, "deployment", "target02" ) },
+          { remote_dir: File.join( Dir.pwd, "deployment", "target03" ) }
+        ]
+      end
+    end
+
+    after :each do
+      Given.cleanup!
+    end
+
+    it "lists currently deployed releases" do
+      output = catch_stdout do
+        @subject.list_releases
+      end
+
+      expect( output ).to match /->(.+?)localhost(.+?)\[\"1372040000\", \"1372030000\"\]/
+    end
+
+  end
+
+end