capistrano-windows-server 0.1.0 → 0.2.0

data/README.md

@@ -0,0 +1,239 @@
+capistrano-windows-server
+=========================
+
+Deploy Ruby on Rails applications with capistrano to Windows servers
+
+Capistrano is the preferred deploy method for Ruby on Rails apps, but Windows isn't really supported.
+We didn't really like having a separate workflow for the projects on that require Windows though,
+so this is what we came up with at SciMed.
+
+Currently, only git is supported, but it could potentially support others.
+There's plenty of room for improvement here, so feel free to fork and contribute.
+
+### How this is different from a normal capistrano setup
+
+capistrano-windows-server provides a level of convenience for deploying to Windows servers, 
+but some things you might expect from a normal capistrano deploy are not possible.
+Windows filesystems do not support symlinks, and files cannot be moved or deleted while they are in use (the server is running).
+
+* Your app will deploy directly to #{deploy_to}/current and update in-place.
+  When you deploy, capistrano is essentially doing a git pull.
+* There is no releases/ directory, and only one copy of your app will be on the server at any time.
+  This means that you cannot roll back.
+* Git submodules are not yet supported by WindowsGit. Instructions for dealing with that are below.
+
+### Server stack
+
+This gem assumes you are working with the following application stack, but you can modify it to meet your needs.
+
+* Ruby on Rails application
+* Mongrel instances proxied behind another web server (Apache + Passenger, nginx)
+* Git code repository
+
+
+Setting up the Windows server
+-----------------------------
+
+This section walks you through setting up SSH and Git on the windows server to prepare it for the deploy.
+These instruction are for Windows Server 2003. For other versions, YMMV.
+Administrative access is required.
+
+* Disable User Access Control. We'll re-enable this later. Reboot if necessary.
+  <br><br>
+  *Control Panel > Users > Notify never*
+  
+* Purchase and install WindowsGit from www.windowsgit.com ($9).
+  <br><br>
+  Yes, you should buy this. I wasted hours trying to get msysgit and COPSSH to work together.
+  If your time is worth more than $3/hr, then this is well worth your money.
+  
+* WindowsGit creates a git user. Make the git user an administrator. This is required, or you will run into
+  [this problem](http://stackoverflow.com/questions/4516111/stack-trace-sshd-exe-fatal-error-could-not-load-u-win32-error-1114-copss/4518324).
+  <br><br>
+  *Administrative Tools > Computer Management > System Tools > Local Users and Groups > Users > git's properties > Member Of > Add "Administrators"*
+  
+* Open the COPSSH Control Panel
+  <br><br>
+  *Start Menu > Programs > Copssh > 01 COPSSH Control Panel*
+  
+* Active the git user for SSH
+  <br><br>
+  *Users > Add*
+  
+* *Recommended:* Disallow password authentication, and use SSH key-based authentication
+
+* Import your developers/deployers' public SSH keys
+  <br><br>
+  *Keys > Import: Paste in public keys; import one at a time.*
+  
+* Re-enable User Access Control
+  <br><br>
+  *Control Panel > Users >* (restore previous value)
+
+Now that COPSSH is up and running, ensure that you can SSH into the server as the git user. If you have problems, check the COPSSH event log under the Status tab. Make sure $HOME/.ssh/authorized_keys contains the keys you added.
+
+If you haven't already, set up Ruby and install any gems needed for your application, plus mongrel.
+The capistrano recipes in this gem create mongrel Windows services to run your app.
+You can use Apache or your web server of choice to proxy for your mongrel instances.
+
+
+Setting up capistrano for your Rails project
+--------------------------------------------
+
+**Rails 2.x**: Add the capistrano-windows-server gem to your Gemfile, and run `bundle`.
+
+    gem "capistrano-windows-server", :lib => "capistrano"
+
+**Rails 3.x**: Add the capistrano-windows-server environment.rb, and run `rake gems:install`.
+
+    config.gem "capistrano-windows-server", :lib => "capistrano"
+
+Set up capistrano as you normally would.
+The [capistrano wiki](https://github.com/capistrano/capistrano/wiki/2.x-From-The-Beginning) and 
+[capistrano handbook](https://github.com/leehambley/capistrano-handbook/blob/master/index.markdown) are helpful.
+
+Set up your config/deploy.rb:
+
+There are a few configuration values that need to be set in your deploy.rb, in addition to your base application configuration.
+
+    require 'capistrano/ext/windows_server'
+
+    set :rails_env, 'production'
+    set :user, 'git'
+    set :deploy_to, "/cygdrive/c/rails_apps/#{application}" # Deploy to C:\rails_apps\#{application}
+    set :mongrel_instances, (1..3)                          # Create 3 mongrel instances
+    set :mongrel_instance_prefix, 'mongrel_'                # named mongrel_{1..3}
+    set :base_port, 8000                                    # on ports 8000, 8001, 8002
+    
+    set :ruby_exe_path, '/cygdrive/c/ruby/bin/ruby'         # This should be set to the location where Ruby is installed.
+
+Your final config/deploy.rb might look something like this:
+
+    require 'capistrano/ext/windows_server'
+
+    set :application, "windowsy"
+    set :repository, "git@github.com:you/windowsy_rails_app.git"
+    set :repository_host_key, "github.com,207.97.227.239 ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAq2A7hRGmdnm9tUDbO9IDSwBK6TbQa+PXYPCPy6rbTrTtw7PHkccKrpp0yVhp5HdEIcKr6pLlVDBfOLX9QUsyCOV0wzfjIJNlGEYsdlLJizHhbn2mUjvSAHQqZETYP81eFzLQNnPHt4EVVUh7VfDESU84KezmD5QlWpXLmvU31/yMf+Se8xhHTvKSCZIFImWwoG6mbUoWf9nzpIoaSjB+weqqUUmpaaasXVal72J+UX2B+2RPW3RcT0eOzQgqlJL3RKrTJvdsjE3JEAvGq3lGHSZXy28G3skua2SmVi/w4yCE6gbODqnTWlg7+wC604ydGXA8VJiS5ap43JXiUFFAaQ==" # This is optional and comes from .ssh/known_hosts. It prevents the initial deploy host key verification problems.
+
+    set :branch do
+      default_ref = 'master'
+      ref = Capistrano::CLI.ui.ask "Ref to deploy (make sure to push the ref first): [#{default_ref}] "
+      ref = default_ref if ref.empty?
+      ref
+    end
+
+    set :rails_env, 'production'
+    set :user, 'git'
+    set :deploy_to, "/cygdrive/c/rails_apps/#{application}" # Deploy to C:\rails_apps\#{application}
+    set :mongrel_instances, (1..3)                          # Create 3 mongrel instances
+    set :mongrel_instance_prefix, 'mongrel_'                # named mongrel_{1..3}
+    set :base_port, 8000                                    # on ports 8000, 8001, 8002
+
+    set :domain, 'www.windowsy.com'
+    role :app, domain
+    role :web, domain
+    role :db, domain, :primary => true
+    
+
+Cleaning up the server before the initial deploy
+------------------------------------------------
+
+If you don't already have mongrel Windows services installed for your app, skip this step.
+
+`cap deploy:setup` will create new mongrel Windows services based on the new app location, so you'll need to remove the existing ones.
+
+If you're using the same naming scheme as you have configured in deploy.rb (in our example, mongrel_1 to 3),
+then use the deploy:mongrel:remove recipe to remove the services.
+
+    cap deploy:mongrel:remove
+
+Otherwise, remove your old services manually (in a Windows command prompt on the server):
+
+    mongrel service::remove -N old_mongrel_service_name
+
+
+The initial deploy
+------------------
+
+The deploy:setup recipe is a little different for Windows.
+In addition to creating the directory structure, it clones your project into #{deploy_to}/current and installs the mongrel Windows services.
+
+    cap deploy:setup
+
+After `cap deploy:setup` runs successfully, it's time to set up the Rails application.
+Create or copy in config/database.yml, set up the database server, install gems, and anything else you need to do to make the app run.
+Testing to make sure the app will start with `rails script/server -e production` is a good idea.
+
+Once it's ready, you can deploy your app for the first time:
+
+    cap deploy:cold
+
+### Submodules
+
+Unfortunately, WindowsGit [does not currently support submodules](https://github.com/SciMed/capistrano-windows-server/issues/1).
+
+If your project uses submodules, there are a few ways you can deal with this.
+
+* Do it by hand - manually clone each submodule after your initial deploy
+* Install another git distribution (msysgit, PortableGit), and run git submodule init/update in your project directory
+* Pull the missing files out of another git distribution (msysgit, PortableGit) and copy them to C:\Program Files\ICW\bin .
+  If you go this route, please document the process on [this issue](https://github.com/SciMed/capistrano-windows-server/issues/1),
+  so we can update this documentation.
+
+
+Which cap tasks are available?
+------------------------------
+
+As usual, you can use `cap -T` for a full list of capistrano tasks.
+
+The following default capistrano tasks are supported:
+
+* `cap deploy` - Updates the code on the server (essentially just a git pull in the current/ directory)
+* `cap deploy:cold` - Deploy and start the server
+* `cap deploy:start` `cap deploy:stop` `cap deploy:restart` - Stop and start the mongrel services
+* `cap deploy:migrate` - Run migrations
+* `cap deploy:migrations` - Deploy and run migrations
+* `cap deploy:update` - Updates the code without restarting the server
+* `cap deploy:update_code` - Now an alias for deploy:update
+* `cap deploy:upload` - Upload files to the server
+* `cap invoke` - Run a command on the server specified by COMMAND
+* `cap shell` - Open a Begin an interactive Capistrano session
+
+The following new tasks were added:
+
+* `cap deploy:mongrel:setup` - Create mongrel services
+* `cap deploy:mongrel:remove` - Remove mongrel services
+* `cap rake` - Run a rake task, specified by COMMAND. eg: cap rake COMMAND="gems:install"
+
+The following tasks will later be fixed:
+
+* `cap deploy:check`
+* `cap deploy:pending`
+* `cap deploy:pending:diff`
+* `cap deploy:web:enable`
+* `cap deploy:web:disable`
+
+The following tasks were removed:
+
+* `cap deploy:cleanup`
+* `cap deploy:rollback`
+* `cap deploy:symlink`
+
+
+Contributing to capistrano-windows-server
+-----------------------------------------
+
+This gem was created to work on our systems and has not yet been tested on a wide range of systems.
+We would love if you contribute back changes that you make to make it work for you.
+ 
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
+* Fork the project
+* Start a feature/bugfix branch
+* Commit and push until you are happy with your contribution
+
+
+Copyright
+---------
+
+Copyright (c) 2011 SciMed Solutions, Inc. See LICENSE.txt for further details.

data/VERSION

@@ -1 +1 @@
-0.1.0
+0.2.0

data/capistrano-windows-server.gemspec

@@ -0,0 +1,53 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{capistrano-windows-server}
+  s.version = "0.2.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Edward Anderson"]
+  s.date = %q{2011-07-22}
+  s.description = %q{This gem modifies capistrano recipes to allow deploys to windows machines.
+Several nuances such as the lack of symlinks make the deploy a little different, but it's better than doing it by hand.
+See the github page for instruction on how to set up Windows to get it ready for a deploy.}
+  s.email = %q{edward.anderson@scimedsolutions.com}
+  s.extra_rdoc_files = [
+    "LICENSE.txt",
+    "README.md"
+  ]
+  s.files = [
+    ".document",
+    "Gemfile",
+    "Gemfile.lock",
+    "LICENSE.txt",
+    "README.md",
+    "Rakefile",
+    "VERSION",
+    "capistrano-windows-server.gemspec",
+    "lib/capistrano/ext/windows_server.rb"
+  ]
+  s.homepage = %q{http://github.com/nilbus/capistrano-windows-server}
+  s.licenses = ["MIT"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.4.2}
+  s.summary = %q{Deploy Ruby on Rails applications with Capistrano to Windows servers}
+
+  if s.respond_to? :specification_version then
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<capistrano>, [">= 0"])
+      s.add_development_dependency(%q<jeweler>, ["~> 1.6.4"])
+    else
+      s.add_dependency(%q<capistrano>, [">= 0"])
+      s.add_dependency(%q<jeweler>, ["~> 1.6.4"])
+    end
+  else
+    s.add_dependency(%q<capistrano>, [">= 0"])
+    s.add_dependency(%q<jeweler>, ["~> 1.6.4"])
+  end
+end
+

data/lib/capistrano/{windows_server.rb → ext/windows_server.rb}

@@ -5,22 +5,23 @@ configuration = Capistrano::Configuration.respond_to?(:instance) ?
 configuration.load do
   set :scm, :git
   set :deploy_via, :remote_cache
-  set :git_enable_submodules, false # Git submodules not supported on windows
+  #set :git_enable_submodules, false # Git submodules not supported on windows
   set :shared_dir, "."
   set :repository_cache, "current"
   set :scm_verbose, true
   set :use_sudo, false
 
   namespace :deploy do
-    desc "Custom for Windows - no releases; just update git in place"
+    desc "Update the code on the server by doing a git pull in the current/ directory"
     task :update do
-      # update_repository_cache will attempt to clean out the repository; we must prevent that with this deploy method.
+      # update_repository_cache will attempt to clean out the repository; we must prevent that.
       # /bin/git below is where www.windowsgit.com's windows git/ssh installation puts the git executable.
+      # This creates a git proxy that goes in $PATH before /bin, which will filter out any `git clean` commands.
       run "mkdir -p '#{shared_path}/bin'"
       run <<-RUN
         echo 'if [ "$1" != "clean" ]; then /bin/git $*; fi' > "#{shared_path}/bin/git.exe"
       RUN
-      alter_path_cmd = "export PATH=#{shared_path}/bin:$PATH"
+      alter_path_cmd = "export PATH=#{shared_path}/bin:$PATH # Required for capistrano-windows-server"
       run <<-RUN
         if ! grep '#{alter_path_cmd}' ~/.bashrc > /dev/null; then echo '#{alter_path_cmd}' >> ~/.bashrc; fi
       RUN
@@ -28,7 +29,7 @@ configuration.load do
       strategy.send 'update_repository_cache'
     end
 
-    desc "On windows, this is an alias for update"
+    desc "An alias for deploy:update"
     task :update_code do
       update
     end
@@ -54,33 +55,37 @@ configuration.load do
       end
     end
 
-    # Do nothing for Windows
-    task :finalize_update do; end
-
-    # Do nothing for Windows
-    task :symlink do; end
+    # Remove tasks that are not appropriate on Windows
+    %w(finalize_update symlink cleanup).each do |removed_task|
+      task removed_task do; end
+    end
+    namespace :rollback do
+      %w(code default).each do |removed_task|
+        task removed_task do; end
+      end
+    end
 
-    desc "Run migrations"
+    desc "Run pending migrations"
     task :migrate do
       set :rake_cmd, "#{ruby_exe_path} -e \"require 'rubygems'; gem 'rake', '>= 0'; load Gem.bin_path('rake', 'rake', '>= 0')\""
       run "cd #{current_path} && #{rake_cmd} db:migrate RAILS_ENV=#{rails_env}"
     end
 
-    desc "start mongrel"
+    desc "Start mongrel"
     task :start do
       mongrel_instances.each do |n|
         run "net start #{mongrel_instance_prefix}#{n}"
       end
     end
 
-    desc "stop mongrel"
+    desc "Stop mongrel"
     task :stop do
       mongrel_instances.each do |n|
         run "net stop #{mongrel_instance_prefix}#{n}"
       end
     end
 
-    desc "restart mongrel"
+    desc "Restart mongrel"
     task :restart do
       mongrel_instances.each do |n|
         run "net stop #{mongrel_instance_prefix}#{n}"
@@ -89,7 +94,7 @@ configuration.load do
     end
 
     namespace :mongrel do
-      desc "create mongrel services"
+      desc "Create mongrel services"
       task :setup do
         mongrel_instances.each do |n|
           run "cd #{current_path} && #{mongrel_cmd} service::install -e #{rails_env} -N #{mongrel_instance_prefix}#{n} -p #{base_port + n - mongrel_instances.first}"
@@ -97,7 +102,7 @@ configuration.load do
         end
       end
 
-      desc "remove mongrel services"
+      desc "Remove mongrel services"
       task :remove do
         set :mongrel_cmd, "#{ruby_exe_path} -e \"require 'rubygems'; gem 'mongrel', '>= 0'; load Gem.bin_path('mongrel', 'mongrel_rails', '>= 0')\""
         mongrel_instances.each do |n|
@@ -109,11 +114,11 @@ configuration.load do
 
   end
 
-  desc "Run a rake command in CMD"
+  desc "Run a rake command in COMMAND"
   task :rake do
-    raise "Specify the command with CMD='some:task with_arguments'" unless ENV['CMD']
+    raise "Specify the command with COMMAND='some:task with_arguments'" unless ENV['COMMAND']
     set :rake_cmd, "#{ruby_exe_path} -e \"require 'rubygems'; gem 'rake', '>= 0'; load Gem.bin_path('rake', 'rake', '>= 0')\""
-    run "cd #{current_path} && #{rake_cmd} #{ENV['CMD']} RAILS_ENV=#{rails_env}"
+    run "cd #{current_path} && #{rake_cmd} #{ENV['COMMAND']} RAILS_ENV=#{rails_env}"
   end
 
   after 'deploy:setup', 'deploy:update_code'

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: capistrano-windows-server
 version: !ruby/object:Gem::Version 
-  hash: 27
+  hash: 23
   prerelease: 
   segments: 
   - 0
-  - 1
+  - 2
   - 0
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Edward Anderson
@@ -59,16 +59,17 @@ extensions: []
 
 extra_rdoc_files: 
 - LICENSE.txt
-- README.rdoc
+- README.md
 files: 
 - .document
 - Gemfile
 - Gemfile.lock
 - LICENSE.txt
-- README.rdoc
+- README.md
 - Rakefile
 - VERSION
-- lib/capistrano/windows_server.rb
+- capistrano-windows-server.gemspec
+- lib/capistrano/ext/windows_server.rb
 has_rdoc: true
 homepage: http://github.com/nilbus/capistrano-windows-server
 licenses: 

data/README.rdoc

@@ -1,20 +0,0 @@
-= capistrano-windows-server
-
-Deploy Ruby on Rails applications with Capistrano to Windows servers
-
-This gem modifies capistrano recipes to allow deploys to windows machines.
-Several nuances such as the lack of symlinks make the deploy a little different, but it's better than doing it by hand.
-See the github page for instruction on how to set up Windows to get it ready for a deploy.
-
-== Contributing to capistrano-windows-server
- 
-* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
-* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
-* Fork the project
-* Start a feature/bugfix branch
-* Commit and push until you are happy with your contribution
-* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
-
-== Copyright
-
-Copyright (c) 2011 SciMed Solutions, Inc. See LICENSE.txt for further details.