Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 237 lines (162 sloc) 10.61 kB
1421971 @nilbus Documentation
nilbus authored
1 capistrano-windows-server
2 =========================
3
4 Deploy Ruby on Rails applications with capistrano to Windows servers
5
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.
9
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.
12
13 ### How this is different from a normal capistrano setup
14
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).
18
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.
24
25 ### Server stack
26
27 This gem assumes you are working with the following application stack, but you can modify it to meet your needs.
28
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
32
33 Setting up the Windows server
34 -----------------------------
35
36 This section walks you through setting up SSH and Git on the windows server to prepare it for the deploy.
37 These instruction are for Windows Server 2003. For other versions, YMMV.
38 Administrative access is required.
39
40 * Disable User Access Control. We'll re-enable this later. Reboot if necessary.
ff56fa1 @nilbus Document available capistrano tasks
nilbus authored
41 <br><br>
1421971 @nilbus Documentation
nilbus authored
42 *Control Panel > Users > Notify never*
43
ff56fa1 @nilbus Document available capistrano tasks
nilbus authored
44 * Purchase and install WindowsGit from www.windowsgit.com ($9).
45 <br><br>
1421971 @nilbus Documentation
nilbus authored
46 Yes, you should buy this. I wasted hours trying to get msysgit and COPSSH to work together.
47 If your time is worth more than $3/hr, then this is well worth your money.
48
49 * WindowsGit creates a git user. Make the git user an administrator. This is required, or you will run into
50 [this problem](http://stackoverflow.com/questions/4516111/stack-trace-sshd-exe-fatal-error-could-not-load-u-win32-error-1114-copss/4518324).
ff56fa1 @nilbus Document available capistrano tasks
nilbus authored
51 <br><br>
1421971 @nilbus Documentation
nilbus authored
52 *Administrative Tools > Computer Management > System Tools > Local Users and Groups > Users > git's properties > Member Of > Add "Administrators"*
53
54 * Open the COPSSH Control Panel
ff56fa1 @nilbus Document available capistrano tasks
nilbus authored
55 <br><br>
1421971 @nilbus Documentation
nilbus authored
56 *Start Menu > Programs > Copssh > 01 COPSSH Control Panel*
57
58 * Active the git user for SSH
ff56fa1 @nilbus Document available capistrano tasks
nilbus authored
59 <br><br>
1421971 @nilbus Documentation
nilbus authored
60 *Users > Add*
61
62 * *Recommended:* Disallow password authentication, and use SSH key-based authentication
63
64 * Import your developers/deployers' public SSH keys
ff56fa1 @nilbus Document available capistrano tasks
nilbus authored
65 <br><br>
1421971 @nilbus Documentation
nilbus authored
66 *Keys > Import: Paste in public keys; import one at a time.*
67
68 * Re-enable User Access Control
ff56fa1 @nilbus Document available capistrano tasks
nilbus authored
69 <br><br>
1421971 @nilbus Documentation
nilbus authored
70 *Control Panel > Users >* (restore previous value)
71
72 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.
73
74 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
75 The capistrano recipes in this gem create mongrel Windows services to run your app.
1421971 @nilbus Documentation
nilbus authored
76 You can use Apache or your web server of choice to proxy for your mongrel instances.
77
78
79 Setting up capistrano for your Rails project
80 --------------------------------------------
81
82 **Rails 2.x**: Add the capistrano-windows-server gem to your Gemfile, and run `bundle`.
83
84 gem "capistrano-windows-server", :lib => "capistrano"
85
86 **Rails 3.x**: Add the capistrano-windows-server environment.rb, and run `rake gems:install`.
87
88 config.gem "capistrano-windows-server", :lib => "capistrano"
89
ff56fa1 @nilbus Document available capistrano tasks
nilbus authored
90 Set up capistrano as you normally would.
1421971 @nilbus Documentation
nilbus authored
91 The [capistrano wiki](https://github.com/capistrano/capistrano/wiki/2.x-From-The-Beginning) and
92 [capistrano handbook](https://github.com/leehambley/capistrano-handbook/blob/master/index.markdown) are helpful.
93
94 Set up your config/deploy.rb:
95
96 There are a few configuration values that need to be set in your deploy.rb, in addition to your base application configuration.
97
98 require 'capistrano/windows_server'
99
100 set :rails_env, 'production'
101 set :user, 'git'
102 set :deploy_to, "/cygdrive/c/rails_apps/#{application}" # Deploy to C:\rails_apps\#{application}
103 set :mongrel_instances, (1..3) # Create 3 mongrel instances
104 set :mongrel_instance_prefix, 'mongrel_' # named mongrel_{1..3}
105 set :base_port, 8000 # on ports 8000, 8001, 8002
106
107 set :ruby_exe_path, '/cygdrive/c/ruby/bin/ruby' # This should be set to the location where Ruby is installed.
108
109 Your final config/deploy.rb might look something like this:
110
111 require 'capistrano/windows_server'
112
113 set :application, "windowsy"
114 set :repository, "git@github.com:you/windowsy_rails_app.git"
115 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.
116
117 set :branch do
118 default_ref = 'master'
119 ref = Capistrano::CLI.ui.ask "Ref to deploy (make sure to push the ref first): [#{default_ref}] "
120 ref = default_ref if ref.empty?
121 ref
122 end
123
124 set :rails_env, 'production'
125 set :user, 'git'
126 set :deploy_to, "/cygdrive/c/rails_apps/#{application}" # Deploy to C:\rails_apps\#{application}
127 set :mongrel_instances, (1..3) # Create 3 mongrel instances
128 set :mongrel_instance_prefix, 'mongrel_' # named mongrel_{1..3}
129 set :base_port, 8000 # on ports 8000, 8001, 8002
130
131 set :domain, 'www.windowsy.com'
132 role :app, domain
133 role :web, domain
134 role :db, domain, :primary => true
135
136
137 Cleaning up the server before the initial deploy
138 ------------------------------------------------
139
ff56fa1 @nilbus Document available capistrano tasks
nilbus authored
140 If you don't already have mongrel Windows services installed for your app, skip this step.
141
142 `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
143
144 If you're using the same naming scheme as you have configured in deploy.rb (in our example, mongrel_1 to 3),
145 then use the deploy:mongrel:remove recipe to remove the services.
146
147 cap deploy:mongrel:remove
148
149 Otherwise, remove your old services manually (in a Windows command prompt on the server):
150
151 mongrel service::remove -N old_mongrel_service_name
152
153
154 The initial deploy
155 ------------------
156
157 The deploy:setup recipe is a little different for Windows.
ff56fa1 @nilbus Document available capistrano tasks
nilbus authored
158 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
159
160 cap deploy:setup
161
162 After `cap deploy:setup` runs successfully, it's time to set up the Rails application.
163 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.
164 Testing to make sure the app will start with `rails script/server -e production` is a good idea.
165
166 Once it's ready, you can deploy your app for the first time:
167
168 cap deploy:cold
169
170 ### Submodules
171
172 Unfortunately, WindowsGit [does not currently support submodules](https://github.com/SciMed/capistrano-windows-server/issues/1).
ff56fa1 @nilbus Document available capistrano tasks
nilbus authored
173
1421971 @nilbus Documentation
nilbus authored
174 If your project uses submodules, there are a few ways you can deal with this.
175
176 * Do it by hand - manually clone each submodule after your initial deploy
177 * Install another git distribution (msysgit, PortableGit), and run git submodule init/update in your project directory
178 * 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
179 If you go this route, please document the process on [this issue](https://github.com/SciMed/capistrano-windows-server/issues/1),
1421971 @nilbus Documentation
nilbus authored
180 so we can update this documentation.
181
ff56fa1 @nilbus Document available capistrano tasks
nilbus authored
182 Which cap tasks are available?
183 ------------------------------
184
185 As usual, you can use `cap -T` for a full list of capistrano tasks.
186
187 The following default capistrano tasks are supported:
188
189 * `cap deploy` - Updates the code on the server (essentially just a git pull in the current/ directory)
190 * `cap deploy:cold` - Deploy and start the server
191 * `cap deploy:start` `cap deploy:stop` `cap deploy:restart` - Stop and start the mongrel services
192 * `cap deploy:migrate` - Run migrations
193 * `cap deploy:migrations` - Deploy and run migrations
194 * `cap deploy:update` - Updates the code without restarting the server
195 * `cap deploy:update_code` - Now an alias for deploy:update
196 * `cap deploy:upload` - Upload files to the server
197 * `cap invoke` - Run a command on the server specified by COMMAND
198 * `cap shell` - Open a Begin an interactive Capistrano session
199
200 The following new tasks were added:
201
202 * `cap deploy:mongrel:setup` - Create mongrel services
203 * `cap deploy:mongrel:remove` - Remove mongrel services
204 * `cap rake` - Run a rake task, specified by COMMAND. eg: cap rake COMMAND="gems:install"
205
206 The following tasks will later be fixed:
207
208 * `cap deploy:check`
209 * `cap deploy:pending`
210 * `cap deploy:pending:diff`
211 * `cap deploy:web:enable`
212 * `cap deploy:web:disable`
213
214 The following tasks were removed:
215
216 * `cap deploy:cleanup`
217 * `cap deploy:rollback`
218 * `cap deploy:symlink`
219
220
1421971 @nilbus Documentation
nilbus authored
221 Contributing to capistrano-windows-server
222 -----------------------------------------
223
224 This gem was created to work on our systems and has not yet been tested on a wide range of systems.
225 We would love if you contribute back changes that you make to make it work for you.
226
227 * Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
228 * Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
229 * Fork the project
230 * Start a feature/bugfix branch
231 * Commit and push until you are happy with your contribution
232
233 Copyright
234 ---------
235
236 Copyright (c) 2011 SciMed Solutions, Inc. See LICENSE.txt for further details.
Something went wrong with that request. Please try again.