capistrano 3.3.5 → 3.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA1:
3
- metadata.gz: c070509b8ffb4ed5817485be5837b7f33b98a99c
4
- data.tar.gz: 08c9555174d74715e0615738d7deb4f472e77595
3
+ metadata.gz: 55a3a0f0c912740b1871ed0152eec9b013ab4274
4
+ data.tar.gz: 826d603280078a95e759d5620b94308f7a3937ab
5
5
  SHA512:
6
- metadata.gz: 338b464cb5443d6ce1f63a121637c5d3acb5c8b956add0b7a0af1fbd27d92d57ebf34ecb052dccdd6ff1d7fb1579cbc54027a9c4d219b6dc269998af6457bdfb
7
- data.tar.gz: d4e7ab991450dc7f6072137b09e10e5500cbbb79c536896b8b4228a4976cd6e7a37dd57970d3908662d2083e78457a4376d45d0144e753bc13a50f307cfc9544
6
+ metadata.gz: 5ccedfa13ac44999dca4ab7f510259ef276123be707edc647b09b270bed65228b64e7c06f4fd771aab441b89c9aad1cf431156ec56d54ad582fffa7f3645a601
7
+ data.tar.gz: aa2fb629595143fbcc4e64e914028d54039e6602bbc570c01b49196c1a67d2b4f127597c66f2310bd31cdd4fd81f3f0cd36e4da016fd5d2cba1685f9d9f735df
@@ -10,3 +10,4 @@ cache: bundler
10
10
  branches:
11
11
  except:
12
12
  - legacy-v2
13
+ sudo: false
@@ -4,7 +4,41 @@ Reverse Chronological Order:
4
4
 
5
5
  ## master
6
6
 
7
- https://github.com/capistrano/capistrano/compare/v3.3.5...HEAD
7
+ https://github.com/capistrano/capistrano/compare/v3.4.0...HEAD
8
+
9
+ ## `3.4.0`
10
+
11
+ https://github.com/capistrano/capistrano/compare/v3.3.5...v3.4.0
12
+
13
+ * Fixed fetch revision for annotated git tags. (@igorsokolov)
14
+ * Fixed updating roles when custom user or port is specified. (@ayastreb)
15
+ * Disables statistics collection.
16
+
17
+ * `bin/` is not suggested to be in `linked_dirs` anymore (@kirs)
18
+ * bin/ is often checked out into repo
19
+ * https://github.com/capistrano/bundler/issues/45#issuecomment-69349237
20
+
21
+ * Bugfix:
22
+ * release_roles did not honour additional property filtering (@townsen)
23
+ * Refactored and simplified property filtering code (@townsen)
24
+
25
+ * Breaking Changes
26
+ * Hosts with the same name are now consolidated into one irrespective of the
27
+ user and port. This allows multiple declarations of a server to be made safely.
28
+ The last declared properties will win. See capistrnorb.com Properties documentation
29
+ for details.
30
+ * Inside the on() block the host variable is now a copy of the host, so changes can be
31
+ made within the block (such as dynamically overriding the user) that will not persist.
32
+ This is very convenient for switching the SSH user temporarily to 'root' for example.
33
+
34
+ * Minor changes
35
+ * Add role_properties() method (see capistrano.github.io PR for doc) (@townsen)
36
+ * Add equality syntax ( eg. port: 1234) for property filtering (@townsen)
37
+ * Add documentation regarding property filtering (@townsen)
38
+ * Clarify wording and recommendation in stage template. (@Kriechi)
39
+ * Both available syntaxes provide similar functionality, do not use both for the same server+role combination.
40
+ * Allow specification of repo_path using stage variable
41
+ default is as before (@townsen)
8
42
 
9
43
  ## `3.3.5`
10
44
 
@@ -52,7 +86,6 @@ https://github.com/capistrano/capistrano/compare/v3.2.1...v3.3.3
52
86
  and --trace options supply it as before.
53
87
 
54
88
  * Disable loading stages configs on `cap -T` (@sponomarev)
55
- * Track (anonymous) statistics, see https://github.com/capistrano/stats
56
89
 
57
90
  * Enhancements (@townsen)
58
91
  * Fix matching on hosts with custom ports or users set
@@ -92,6 +125,7 @@ https://github.com/capistrano/capistrano/compare/v3.2.1...v3.3.3
92
125
 
93
126
  Breaking Changes:
94
127
  * By using Ruby's noecho method introduced in Ruby version 1.9.3, we dropped support for Ruby versions prior to 1.9.3. See [issue #878](https://github.com/capistrano/capistrano/issues/878) and [PR #1112](https://github.com/capistrano/capistrano/pull/1112) for more information. (@kaikuchn)
128
+ * Track (anonymous) statistics, see https://github.com/capistrano/stats. This breaks automated deployment on continuous integration servers until the `.capistrano/metrics` file is created (with content `full` to simulate a "yes") via the interactive prompt or manually.
95
129
 
96
130
  * Bug Fixes:
97
131
  * Fixed compatibility with FreeBSD tar (@robbertkl)
data/README.md CHANGED
@@ -1,16 +1,26 @@
1
1
  # Capistrano [![Build Status](https://travis-ci.org/capistrano/capistrano.svg?branch=master)](https://travis-ci.org/capistrano/capistrano) [![Code Climate](http://img.shields.io/codeclimate/github/capistrano/capistrano.svg)](https://codeclimate.com/github/capistrano/capistrano) <a href="http://codersclan.net/?repo_id=325&source=small"><img src="http://img.shields.io/badge/get-support-blue.svg"></a>
2
2
 
3
- ## Requirements
3
+ ## Documentation
4
4
 
5
- * Ruby >= 1.9.3 (JRuby and C-Ruby/YARV are supported)
5
+ Check out the [online documentation](http://capistranorb.com) of Capistrano 3 hosted via this [repository](https://github.com/capistrano/capistrano.github.io).
6
6
 
7
7
  ## Support
8
8
 
9
9
  Need help with getting Capistrano up and running? Got a code problem you want to get solved quickly?
10
10
 
11
- Get <a href="http://codersclan.net/?repo_id=325&source=link">Capistrano support on CodersClan.</a>
11
+ Get <a href="http://codersclan.net/?repo_id=325&source=link">Capistrano support on CodersClan.</a> <a href="http://codersclan.net/?repo_id=325&source=big"><img src="http://www.codersclan.net/gs_button/?repo_id=325" width="150"></a>
12
+
13
+ ## Requirements
14
+
15
+ * Ruby >= 1.9.3 (JRuby and C-Ruby/YARV are supported)
16
+
17
+ Capistrano support these source code version control systems out of the box:
12
18
 
13
- <a href="http://codersclan.net/?repo_id=325&source=big"><img src="http://www.codersclan.net/gs_button/?repo_id=325" width="200"></a>
19
+ * Git 1.8 or higher
20
+ * Mercurial
21
+ * SVN
22
+
23
+ Binaries for these VCS might be required on the local and/or the remote systems.
14
24
 
15
25
  ## Installation
16
26
 
@@ -55,280 +65,26 @@ $ bundle exec cap install STAGES=local,sandbox,qa,production
55
65
  ## Usage
56
66
 
57
67
  ``` sh
68
+ # list all available tasks
58
69
  $ bundle exec cap -T
59
70
 
71
+ # deploy to the staging environment
60
72
  $ bundle exec cap staging deploy
73
+
74
+ # deploy to the production environment
61
75
  $ bundle exec cap production deploy
62
76
 
77
+ # simulate deploying to the production environment
78
+ # does not actually do anything
63
79
  $ bundle exec cap production deploy --dry-run
64
- $ bundle exec cap production deploy --prereqs
65
- $ bundle exec cap production deploy --trace
66
- ```
67
-
68
- ## Tasks
69
80
 
70
- ``` ruby
71
- server 'example.com', roles: [:web, :app]
72
- server 'example.org', roles: [:db, :workers]
73
- desc "Report Uptimes"
74
- task :uptime do
75
- on roles(:all) do |host|
76
- execute :any_command, "with args", :here, "and here"
77
- info "Host #{host} (#{host.roles.to_a.join(', ')}):\t#{capture(:uptime)}"
78
- end
79
- end
80
- ```
81
-
82
- **Note**:
83
-
84
- **tl;dr**: `execute(:bundle, :install)` and `execute('bundle install')` don't behave identically!
85
-
86
- `execute()` has a subtle behaviour. When calling `within './directory' { execute(:bundle, :install) }` for example, the first argument to `execute()` is a *Stringish* with ***no whitespace***. This allows the command to pass through the [SSHKit::CommandMap](https://github.com/capistrano/sshkit#the-command-map) which enables a number of powerful features.
87
-
88
- When the first argument to `execute()` contains whitespace, for example `within './directory' { execute('bundle install') }` (or when using a heredoc), neither Capistrano, nor SSHKit can reliably predict how it should be shell escaped, and thus cannot perform any context, or command mapping, that means that the `within(){}` (as well as `with()`, `as()`, etc) have no effect. There have been a few attempts to resolve this, but we don't consider it a bug although we acknowledge that it might be a little counter intuitive.
89
- ## Before / After
90
-
91
- Where calling on the same task name, executed in order of inclusion
92
-
93
- ``` ruby
94
- # call an existing task
95
- before :starting, :ensure_user
96
-
97
- after :finishing, :notify
98
-
99
-
100
- # or define in block
101
- before :starting, :ensure_user do
102
- #
103
- end
104
-
105
- after :finishing, :notify do
106
- #
107
- end
108
- ```
109
-
110
- If it makes sense for your use case (often, that means *generating a file*)
111
- the Rake prerequisite mechanism can be used:
112
-
113
- ``` ruby
114
- desc "Create Important File"
115
- file 'important.txt' do |t|
116
- sh "touch #{t.name}"
117
- end
118
- desc "Upload Important File"
119
- task :upload => 'important.txt' do |t|
120
- on roles(:all) do
121
- upload!(t.prerequisites.first, '/tmp')
122
- end
123
- end
124
- ```
125
-
126
- The final way to call out to other tasks is to simply `invoke()` them:
127
-
128
- ``` ruby
129
- namespace :example do
130
- task :one do
131
- on roles(:all) { info "One" }
132
- end
133
- task :two do
134
- invoke "example:one"
135
- on roles(:all) { info "Two" }
136
- end
137
- end
138
- ```
139
-
140
- This method is widely used.
141
-
142
- ## Getting User Input
143
-
144
- ``` ruby
145
- desc "Ask about breakfast"
146
- task :breakfast do
147
- ask(:breakfast, "pancakes")
148
- on roles(:all) do |h|
149
- execute "echo \"$(whoami) wants #{fetch(:breakfast)} for breakfast!\""
150
- end
151
- end
152
- ```
153
-
154
- Perfect, who needs telephones.
155
-
156
- When using `ask` to get user input, you can pass `echo: false` to prevent the input from being displayed:
157
-
158
- ```ruby
159
- ask(:database_password, "default", echo: false)
160
- ```
161
-
162
- ## Using password authentication
163
-
164
- Password authentication can be done via `set` and `ask` in your deploy environment file (e.g.: config/deploy/production.rb)
165
-
166
- ```ruby
167
- set :password, ask('Server password', nil)
168
- server 'server.domain.com', user: 'ssh_user_name', port: 22, password: fetch(:password), roles: %w{web app db}
169
- ```
170
-
171
- ## Running local tasks
172
-
173
- Local tasks can be run by replacing `on` with `run_locally`
174
-
175
- ``` ruby
176
- desc 'Notify service of deployment'
177
- task :notify do
178
- run_locally do
179
- with rails_env: :development do
180
- rake 'service:notify'
181
- end
182
- end
183
- end
184
- ```
185
-
186
- Of course, you can always just use standard ruby syntax to run things locally
187
- ``` ruby
188
- desc 'Notify service of deployment'
189
- task :notify do
190
- %x('RAILS_ENV=development bundle exec rake "service:notify"')
191
- end
192
- ```
193
-
194
- Alternatively you could use the rake syntax
195
- ``` ruby
196
- desc "Notify service of deployment"
197
- task :notify do
198
- sh 'RAILS_ENV=development bundle exec rake "service:notify"'
199
- end
200
- ```
201
- ## Console
202
-
203
- **Note:** Here be dragons. The console is very immature, but it's much more
204
- cleanly architected than previous incarnations and it'll only get better from
205
- here on in.
206
-
207
- Execute arbitrary remote commands, to use this simply add
208
- `require 'capistrano/console'` which will add the necessary tasks to your
209
- environment:
210
-
211
- ``` sh
212
- $ bundle exec cap staging console
213
- ```
214
-
215
- Then, after setting up the server connections, this is how that might look:
81
+ # list task dependencies
82
+ $ bundle exec cap production deploy --prereqs
216
83
 
217
- ``` sh
218
- $ bundle exec cap production console
219
- capistrano console - enter command to execute on production
220
- production> uptime
221
- INFO [94db8027] Running /usr/bin/env uptime on leehambley@example.com:22
222
- DEBUG [94db8027] Command: /usr/bin/env uptime
223
- DEBUG [94db8027] 17:11:17 up 50 days, 22:31, 1 user, load average: 0.02, 0.02, 0.05
224
- INFO [94db8027] Finished in 0.435 seconds command successful.
225
- production> who
226
- INFO [9ce34809] Running /usr/bin/env who on leehambley@example.com:22
227
- DEBUG [9ce34809] Command: /usr/bin/env who
228
- DEBUG [9ce34809] leehambley pts/0 2013-06-13 17:11 (port-11262.pppoe.wtnet.de)
229
- INFO [9ce34809] Finished in 0.420 seconds command successful.
84
+ # trace through task invocations
85
+ $ bundle exec cap production deploy --trace
230
86
  ```
231
87
 
232
- ## VCS Requirements
233
-
234
- Capistano requires modern versions of Git, Mercurial and Subversion
235
- respectively (if you are using that particular VCS). Git requirement is at
236
- least version 1.8.x. Mercurial and Subversion, any modern version should
237
- suffice.
238
-
239
- ## A word about PTYs
240
-
241
- There is a configuration option which asks the backend driver to ask the remote host
242
- to assign the connection a *pty*. A *pty* is a pseudo-terminal, which in effect means
243
- *tell the backend that this is an __interactive__ session*. This is normally a bad idea.
244
-
245
- Most of the differences are best explained by [this page](https://github.com/sstephenson/rbenv/wiki/Unix-shell-initialization) from the author of *rbenv*.
246
-
247
- **When Capistrano makes a connection it is a *non-login*, *non-interactive* shell.
248
- This was not an accident!**
249
-
250
- It's often used as a band aid to cure issues related to RVM and rbenv not loading login
251
- and shell initialisation scripts. In these scenarios RVM and rbenv are the tools at fault,
252
- or at least they are being used incorrectly.
253
-
254
- Whilst, especially in the case of language runtimes (Ruby, Node, Python and friends in
255
- particular) there is a temptation to run multiple versions in parallel on a single server
256
- and to switch between them using environmental variables, this is an anti-pattern, and
257
- symptomatic of bad design (e.g. you're testing a second version of Ruby in production because
258
- your company lacks the infrastructure to test this in a staging environment).
259
-
260
- ## Configuration
261
-
262
- The following variables are settable:
263
-
264
- | Variable Name | Description | Notes |
265
- |:---------------------:|----------------------------------------------------------------------|-----------------------------------------------------------------|
266
- | `:repo_url` | The URL of your scm repository (git, hg, svn) | file://, https://, ssh://, or svn+ssh:// are all supported |
267
- | `:repo_tree` | The subtree of the scm repository to deploy (git, hg) | Only implemented for git and hg repos. Extract just this tree |
268
- | `:branch` | The branch you wish to deploy | This only has meaning for git and hg repos, to specify the branch of an svn repo, set `:repo_url` to the branch location. |
269
- | `:scm` | The source control system used | `:git`, `:hg`, `:svn` are currently supported |
270
- | `:tmp_dir` | The (optional) temp directory that will be used (default: /tmp) | if you have a shared web host, this setting may need to be set (i.e. /home/user/tmp/capistrano). |
271
-
272
- __Support removed__ for following variables:
273
-
274
- | Variable Name | Description | Notes |
275
- |:---------------------:|---------------------------------------------------------------------|-----------------------------------------------------------------|
276
- | `:copy_exclude` | The (optional) array of files and/or folders excluded from deploy | Replaced by Git's native `.gitattributes`, see [#515](https://github.com/capistrano/capistrano/issues/515) for more info. |
277
-
278
- ## Host and Role Filtering
279
-
280
- Capistrano enables the declaration of servers and roles, each of which may have properties
281
- associated with them. Tasks are then able to use these definitions in two distinct ways:
282
-
283
- * To determine _configurations_: typically by using the `roles()`, `release_roles()` and
284
- `primary()` methods. Typically these are used outside the scope of the `on()` method.
285
-
286
- * To _interact_ with remote hosts using the `on()` method
287
-
288
- An example of the two would be to create a `/etc/krb5.conf` file containing the list of
289
- available KDC's by using the list of servers returned by `roles(:kdc)` and then uploading
290
- it to all client machines using `on(roles(:all)) do upload!(file) end`
291
-
292
- A problem with this arises when _filters_ are used. Filters are designed to limit the
293
- actual set of hosts that are used to a subset of those in the overall stage, but how
294
- should that apply in the above case?
295
-
296
- If the filter applies to both the _interaction_ and _configuration_ aspects, any configuration
297
- files deployed will not be the same as those on the hosts excluded by the filters. This is
298
- almost certainly not what is wanted, the filters should apply only to the _interactions_
299
- ensuring that any configuration files deployed will be identical across the stage.
300
-
301
- Another type of filtering is done by defining properties on servers and selecting on that
302
- basis. An example of that is the 'no_release' property and it's use in the
303
- `release_roles()` method. To distinguish these two types of filtering we name them:
304
-
305
- * On-Filtering
306
- Specified in the following ways:
307
- * Via environment variables HOSTS and ROLES
308
- * Via command line options `--hosts` and `--roles`
309
- * Via the `:filter` variable set in a stage file
310
- * Property-Filtering
311
- These are specified by options passed to the `roles()` method (and implicitly in methods
312
- like `release_roles()` and `primary()`)
313
-
314
- To increase the utility of On-Filters they can use regular expressions:
315
- * If the host name in a filter doesn't match `/^[-A-Za-z0-9.]+$/` (the set of valid characters
316
- for a DNS name) then it's assumed to be a regular expression.
317
- * Since role names are Ruby symbols they can legitimately contain any characters. To allow multiple
318
- of them to be specified on one line we use the comma. To use a regexp for a role filter begin
319
- and end the string with '/'. These may not contain a comma.
320
-
321
- When filters are specified using comma separated lists, the final filter is the _union_ of
322
- all of the components. However when multiple filters are declared the result is the
323
- _intersection_.
324
-
325
- ## SSHKit
326
-
327
- [SSHKit](https://github.com/leehambley/sshkit) is the driver for SSH
328
- connections behind the scenes in Capistrano. Depending on how deep you dig, you
329
- might run into interfaces that come directly from SSHKit (the configuration is
330
- a good example).
331
-
332
88
  ## Testing
333
89
 
334
90
  Capistrano has two test suites: an RSpec suite and a Cucumber suite. The
@@ -350,25 +106,12 @@ $ rake features
350
106
  $ rake features KEEP_RUNNING=1
351
107
  ```
352
108
 
353
- ## Metrics
354
-
355
- Since version 3.3.3 Capistrano includes anonymous metrics. The metric server,
356
- gem collection, and when it exists, the HTML/d3 page to view the metrics are
357
- all open-source and available for inspection and audit at
358
- https://github.com/capistrano/stats
359
-
360
- **Notes for CI**: If you commit the file `.capistrano/metrics` to your source
361
- control, you will not be prompted again, this is what we expect you to do, and
362
- it should also avoid breaking your CI server by blocking waiting for an answer
363
- on standard in. The metric prompt is also [disabled when standard in is not a
364
- tty](https://github.com/capistrano/stats/blob/77c9993d3ee604520712261aa2a70c90f3b96a6f/gem/lib/capistrano-stats/metric-collector.rb#L53)
365
- (when using Capistrano from scripts, or from come well behaved CI services)
366
-
367
- * The gem invites users to opt-into metrics collection when the task
368
- `load:defaults` is called. A project-specific hash derived from the output of
369
- `git config remote.origin.url` is written to a file `.capistrano/metrics` to
370
- allow us to differentiate between many members of the same team deploying the
371
- same project vs. many people on many projects.
109
+ ## SSHKit
110
+
111
+ [SSHKit](https://github.com/leehambley/sshkit) is the driver for SSH
112
+ connections behind the scenes in Capistrano. Depending on how deep you dig, you
113
+ might run into interfaces that come directly from SSHKit (the configuration is
114
+ a good example).
372
115
 
373
116
  ## License
374
117
 
@@ -29,7 +29,6 @@ eos
29
29
 
30
30
  gem.required_ruby_version = '>= 1.9.3'
31
31
  gem.add_dependency 'sshkit', '~> 1.3'
32
- gem.add_dependency 'capistrano-stats', '~> 1.1.0'
33
32
  gem.add_dependency 'rake', '>= 10.0.0'
34
33
  gem.add_dependency 'i18n'
35
34
 
@@ -0,0 +1,11 @@
1
+ Feature: SSH Connection
2
+
3
+ Background:
4
+ Given a test app with the default configuration
5
+ And servers with the roles app and web
6
+ And a task which executes as root
7
+
8
+ Scenario: Switching from default user to root and back again
9
+ When I run cap "am_i_root"
10
+ Then the task is successful
11
+ And the output matches "I am uid=0\(root\)" followed by "I am uid=\d+\(vagrant\)"