Skip to content
100644 240 lines (162 sloc) 10.4 KB
1421971 @nilbus Documentation
nilbus authored
1 capistrano-windows-server
2 =========================
4 Deploy Ruby on Rails applications with capistrano to Windows servers
6 Capistrano is the preferred deploy method for Ruby on Rails apps, but Windows isn't really supported.
7 We didn't really like having a separate workflow for the projects on that require Windows though,
8 so this is what we came up with at SciMed.
10 Currently, only git is supported, but it could potentially support others.
11 There's plenty of room for improvement here, so feel free to fork and contribute.
13 ### How this is different from a normal capistrano setup
15 capistrano-windows-server provides a level of convenience for deploying to Windows servers,
16 but some things you might expect from a normal capistrano deploy are not possible.
17 Windows filesystems do not support symlinks, and files cannot be moved or deleted while they are in use (the server is running).
19 * Your app will deploy directly to #{deploy_to}/current and update in-place.
20 When you deploy, capistrano is essentially doing a git pull.
21 * There is no releases/ directory, and only one copy of your app will be on the server at any time.
22 This means that you cannot roll back.
23 * Git submodules are not yet supported by WindowsGit. Instructions for dealing with that are below.
25 ### Server stack
27 This gem assumes you are working with the following application stack, but you can modify it to meet your needs.
29 * Ruby on Rails application
ff56fa1 @nilbus Document available capistrano tasks
nilbus authored
30 * Mongrel instances proxied behind another web server (Apache + Passenger, nginx)
1421971 @nilbus Documentation
nilbus authored
31 * Git code repository
ba63f96 @nilbus Move gem to capistrano/ext
nilbus authored
1421971 @nilbus Documentation
nilbus authored
34 Setting up the Windows server
35 -----------------------------
37 This section walks you through setting up SSH and Git on the windows server to prepare it for the deploy.
38 These instruction are for Windows Server 2003. For other versions, YMMV.
39 Administrative access is required.
41 * Disable User Access Control. We'll re-enable this later. Reboot if necessary.
ff56fa1 @nilbus Document available capistrano tasks
nilbus authored
42 <br><br>
1421971 @nilbus Documentation
nilbus authored
43 *Control Panel > Users > Notify never*
ff56fa1 @nilbus Document available capistrano tasks
nilbus authored
45 * Purchase and install WindowsGit from ($9).
46 <br><br>
1421971 @nilbus Documentation
nilbus authored
47 Yes, you should buy this. I wasted hours trying to get msysgit and COPSSH to work together.
48 If your time is worth more than $3/hr, then this is well worth your money.
50 * WindowsGit creates a git user. Make the git user an administrator. This is required, or you will run into
51 [this problem](
ff56fa1 @nilbus Document available capistrano tasks
nilbus authored
52 <br><br>
1421971 @nilbus Documentation
nilbus authored
53 *Administrative Tools > Computer Management > System Tools > Local Users and Groups > Users > git's properties > Member Of > Add "Administrators"*
55 * Open the COPSSH Control Panel
ff56fa1 @nilbus Document available capistrano tasks
nilbus authored
56 <br><br>
1421971 @nilbus Documentation
nilbus authored
57 *Start Menu > Programs > Copssh > 01 COPSSH Control Panel*
59 * Active the git user for SSH
ff56fa1 @nilbus Document available capistrano tasks
nilbus authored
60 <br><br>
1421971 @nilbus Documentation
nilbus authored
61 *Users > Add*
63 * *Recommended:* Disallow password authentication, and use SSH key-based authentication
65 * Import your developers/deployers' public SSH keys
ff56fa1 @nilbus Document available capistrano tasks
nilbus authored
66 <br><br>
1421971 @nilbus Documentation
nilbus authored
67 *Keys > Import: Paste in public keys; import one at a time.*
69 * Re-enable User Access Control
ff56fa1 @nilbus Document available capistrano tasks
nilbus authored
70 <br><br>
1421971 @nilbus Documentation
nilbus authored
71 *Control Panel > Users >* (restore previous value)
73 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.
75 If you haven't already, set up Ruby and install any gems needed for your application, plus mongrel.
ff56fa1 @nilbus Document available capistrano tasks
nilbus authored
76 The capistrano recipes in this gem create mongrel Windows services to run your app.
1421971 @nilbus Documentation
nilbus authored
77 You can use Apache or your web server of choice to proxy for your mongrel instances.
80 Setting up capistrano for your Rails project
81 --------------------------------------------
83 **Rails 2.x**: Add the capistrano-windows-server gem to your Gemfile, and run `bundle`.
85 gem "capistrano-windows-server", :lib => "capistrano"
87 **Rails 3.x**: Add the capistrano-windows-server environment.rb, and run `rake gems:install`.
89 config.gem "capistrano-windows-server", :lib => "capistrano"
ff56fa1 @nilbus Document available capistrano tasks
nilbus authored
91 Set up capistrano as you normally would.
1421971 @nilbus Documentation
nilbus authored
92 The [capistrano wiki]( and
93 [capistrano handbook]( are helpful.
95 Set up your config/deploy.rb:
97 There are a few configuration values that need to be set in your deploy.rb, in addition to your base application configuration.
ba63f96 @nilbus Move gem to capistrano/ext
nilbus authored
99 require 'capistrano/ext/windows_server'
1421971 @nilbus Documentation
nilbus authored
101 set :rails_env, 'production'
102 set :user, 'git'
103 set :deploy_to, "/cygdrive/c/rails_apps/#{application}" # Deploy to C:\rails_apps\#{application}
104 set :mongrel_instances, (1..3) # Create 3 mongrel instances
105 set :mongrel_instance_prefix, 'mongrel_' # named mongrel_{1..3}
106 set :base_port, 8000 # on ports 8000, 8001, 8002
108 set :ruby_exe_path, '/cygdrive/c/ruby/bin/ruby' # This should be set to the location where Ruby is installed.
110 Your final config/deploy.rb might look something like this:
ba63f96 @nilbus Move gem to capistrano/ext
nilbus authored
112 require 'capistrano/ext/windows_server'
1421971 @nilbus Documentation
nilbus authored
114 set :application, "windowsy"
115 set :repository, ""
116 set :repository_host_key, ", 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.
118 set :branch do
119 default_ref = 'master'
120 ref = Capistrano::CLI.ui.ask "Ref to deploy (make sure to push the ref first): [#{default_ref}] "
121 ref = default_ref if ref.empty?
122 ref
123 end
125 set :rails_env, 'production'
126 set :user, 'git'
127 set :deploy_to, "/cygdrive/c/rails_apps/#{application}" # Deploy to C:\rails_apps\#{application}
128 set :mongrel_instances, (1..3) # Create 3 mongrel instances
129 set :mongrel_instance_prefix, 'mongrel_' # named mongrel_{1..3}
130 set :base_port, 8000 # on ports 8000, 8001, 8002
132 set :domain, ''
133 role :app, domain
134 role :web, domain
135 role :db, domain, :primary => true
138 Cleaning up the server before the initial deploy
139 ------------------------------------------------
ff56fa1 @nilbus Document available capistrano tasks
nilbus authored
141 If you don't already have mongrel Windows services installed for your app, skip this step.
143 `cap deploy:setup` will create new mongrel Windows services based on the new app location, so you'll need to remove the existing ones.
1421971 @nilbus Documentation
nilbus authored
145 If you're using the same naming scheme as you have configured in deploy.rb (in our example, mongrel_1 to 3),
146 then use the deploy:mongrel:remove recipe to remove the services.
148 cap deploy:mongrel:remove
150 Otherwise, remove your old services manually (in a Windows command prompt on the server):
152 mongrel service::remove -N old_mongrel_service_name
155 The initial deploy
156 ------------------
158 The deploy:setup recipe is a little different for Windows.
ff56fa1 @nilbus Document available capistrano tasks
nilbus authored
159 In addition to creating the directory structure, it clones your project into #{deploy_to}/current and installs the mongrel Windows services.
1421971 @nilbus Documentation
nilbus authored
161 cap deploy:setup
163 After `cap deploy:setup` runs successfully, it's time to set up the Rails application.
164 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.
165 Testing to make sure the app will start with `rails script/server -e production` is a good idea.
167 Once it's ready, you can deploy your app for the first time:
169 cap deploy:cold
171 ### Submodules
173 Unfortunately, WindowsGit [does not currently support submodules](
ff56fa1 @nilbus Document available capistrano tasks
nilbus authored
1421971 @nilbus Documentation
nilbus authored
175 If your project uses submodules, there are a few ways you can deal with this.
177 * Do it by hand - manually clone each submodule after your initial deploy
178 * Install another git distribution (msysgit, PortableGit), and run git submodule init/update in your project directory
179 * Pull the missing files out of another git distribution (msysgit, PortableGit) and copy them to C:\Program Files\ICW\bin .
ff56fa1 @nilbus Document available capistrano tasks
nilbus authored
180 If you go this route, please document the process on [this issue](,
1421971 @nilbus Documentation
nilbus authored
181 so we can update this documentation.
ba63f96 @nilbus Move gem to capistrano/ext
nilbus authored
ff56fa1 @nilbus Document available capistrano tasks
nilbus authored
184 Which cap tasks are available?
185 ------------------------------
187 As usual, you can use `cap -T` for a full list of capistrano tasks.
189 The following default capistrano tasks are supported:
191 * `cap deploy` - Updates the code on the server (essentially just a git pull in the current/ directory)
192 * `cap deploy:cold` - Deploy and start the server
193 * `cap deploy:start` `cap deploy:stop` `cap deploy:restart` - Stop and start the mongrel services
194 * `cap deploy:migrate` - Run migrations
195 * `cap deploy:migrations` - Deploy and run migrations
196 * `cap deploy:update` - Updates the code without restarting the server
197 * `cap deploy:update_code` - Now an alias for deploy:update
198 * `cap deploy:upload` - Upload files to the server
199 * `cap invoke` - Run a command on the server specified by COMMAND
200 * `cap shell` - Open a Begin an interactive Capistrano session
202 The following new tasks were added:
204 * `cap deploy:mongrel:setup` - Create mongrel services
205 * `cap deploy:mongrel:remove` - Remove mongrel services
206 * `cap rake` - Run a rake task, specified by COMMAND. eg: cap rake COMMAND="gems:install"
208 The following tasks will later be fixed:
210 * `cap deploy:check`
211 * `cap deploy:pending`
212 * `cap deploy:pending:diff`
213 * `cap deploy:web:enable`
214 * `cap deploy:web:disable`
216 The following tasks were removed:
218 * `cap deploy:cleanup`
219 * `cap deploy:rollback`
220 * `cap deploy:symlink`
1421971 @nilbus Documentation
nilbus authored
223 Contributing to capistrano-windows-server
224 -----------------------------------------
226 This gem was created to work on our systems and has not yet been tested on a wide range of systems.
227 We would love if you contribute back changes that you make to make it work for you.
229 * Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
230 * Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
231 * Fork the project
232 * Start a feature/bugfix branch
233 * Commit and push until you are happy with your contribution
ba63f96 @nilbus Move gem to capistrano/ext
nilbus authored
1421971 @nilbus Documentation
nilbus authored
236 Copyright
237 ---------
239 Copyright (c) 2011 SciMed Solutions, Inc. See LICENSE.txt for further details.
Something went wrong with that request. Please try again.