kotovalexarian-likes-github/capistrano
1
0
Fork 0
mirror of https://github.com/capistrano/capistrano synced 2023-03-27 23:21:18 -04:00
Code Releases Activity

Merge pull request #110 from Kriechi/add-readme-sections

Browse source 
Add readme sections
This commit is contained in:
Lee Hambley 2015-01-19 09:44:05 +01:00
commit c2e80bb804
24 changed files with 329 additions and 149 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
_config.yml
View file

@ -5,6 +5,4 @@ lsi: false
markdown: redcarpet markdown: redcarpet
redcarpet: redcarpet:
extensions: ["no_intra_emphasis", "fenced_code_blocks", "autolink", "tables", "with_toc_data"] extensions: ["no_intra_emphasis", "fenced_code_blocks", "autolink", "tables", "with_toc_data"]
table_of_contents:
dirs: [documentation]
exclude: ["Gemfile", "Gemfile.lock", "README.md"] exclude: ["Gemfile", "Gemfile.lock", "README.md"]

6
_includes/google_tag_manager.html Normal file
View file

@ -0,0 +1,6 @@
<!-- Google Tag Manager -->
<noscript>
<iframe src="//www.googletagmanager.com/ns.html?id=GTM-KLDBJG" height="0" width="0" style="display:none;visibility:hidden"></iframe>
</noscript>
<script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start': new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0], j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src= '//www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f); })(window,document,'script','dataLayer','GTM-KLDBJG');</script>
<!-- End Google Tag Manager -->

80
_includes/navigation.html
View file

@ -1,59 +1,67 @@
<ul class="side-nav"> <ul class="side-nav">
<li><a href="http://goo.gl/4sqEav" title="Harrow | Seamless collaboration for software teams" class="advertisment"><span class="label label-important">New</span> Hosted Capistrano for Teams</a></li> <li><a href="http://goo.gl/4sqEav" title="Harrow | Seamless collaboration for software teams" class="advertisment"><span class="label label-important">New</span> Hosted Capistrano for Teams</a></li>
<li class="divider"></li> <li class="divider"></li>
<h5>Overview</h5> <h5>Overview</h5>
<li><a href="/documentation/overview/what-is-capistrano/">What is Capistrano?</a></li> <li><a href="/documentation/overview/what-is-capistrano/">What is Capistrano?</a></li>
<!--<li><a href="/documentation/overview/introductory-demo-video/">Introductory Demo Video</a></li>-->
<li class="divider"></li> <li class="divider"></li>
<h5>Getting Started</h5> <h5>Getting Started</h5>
<li><a href="https://github.com/capistrano/capistrano/blob/master/README.md">The Readme, start here!</a></li> <li><a href="https://github.com/capistrano/capistrano/blob/master/README.md">The Readme, start here!</a></li>
<li><a href="/documentation/getting-started/installation/">Installation</a></li> <li><a href="/documentation/getting-started/installation/">Installation</a></li>
<li><a href="/documentation/getting-started/configuration/">Configuration</a></li>
<li><a href="/documentation/getting-started/preparing-your-application/">Preparing Your Application</a></li> <li><a href="/documentation/getting-started/preparing-your-application/">Preparing Your Application</a></li>
<li><a href="/documentation/getting-started/authentication-and-authorisation/">Authentication &amp; Authorisation</a></li>
<li><a href="/documentation/getting-started/cold-start/">Cold Start</a></li>
<li><a href="/documentation/getting-started/flow/">Flow</a></li> <li><a href="/documentation/getting-started/flow/">Flow</a></li>
<li><a href="/documentation/getting-started/rollbacks/">Rollbacks</a></li> <li><a href="/documentation/getting-started/rollbacks/">Rollbacks</a></li>
<li><a href="/documentation/upgrading/">Upgrading from 2.x</a></li> <li><a href="/documentation/getting-started/cold-start/">Cold Start</a></li>
<li><a href="/documentation/getting-started/tasks/">Tasks</a></li>
<li><a href="/documentation/getting-started/local-tasks/">Local Tasks</a></li>
<li><a href="/documentation/getting-started/user-input/">User Input</a></li>
<li><a href="/documentation/getting-started/before-after/">Before / After Hooks</a></li>
<li><a href="/documentation/getting-started/authentication-and-authorisation/">Authentication &amp; Authorisation</a></li>
<li><a href="/documentation/getting-started/password-authentication/">Password Authentication</a></li>
<li class="divider"></li> <li class="divider"></li>
<h5>Advanced Features</h5>
<li><a href="/documentation/advanced-features/ssh-kit">Remote commands with SSHKit</li>
<li><a href="/documentation/advanced-features/remote-file/">Remote file task</a></li>
<li><a href="/documentation/advanced-features/role-filtering/">Role filtering</a></li>
<li><a href="/documentation/advanced-features/host-filtering/">Host filtering</a></li>
<li><a href="/documentation/advanced-features/capistrano-pure-ruby/">Using Capistrano from pure Ruby</a></li>
<li><a href="/documentation/advanced-features/overriding-capistrano-tasks/">Overriding Capistrano tasks</a></li>
<h5>Advanced Features</h5>
<li><a href="/documentation/advanced-features/console/">Console</a></li>
<li><a href="/documentation/advanced-features/ptys/">PTYs</a></li>
<li><a href="/documentation/advanced-features/host-and-role-filtering/">Host and Role Filtering</a></li>
<li><a href="/documentation/advanced-features/host-filtering/">Host filtering</a></li>
<li><a href="/documentation/advanced-features/role-filtering/">Role Filtering</a></li>
<li><a href="/documentation/advanced-features/overriding-capistrano-tasks/">Overriding Capistrano Tasks</a></li>
<li><a href="/documentation/advanced-features/capistrano-pure-ruby/">Using Capistrano from Pure Ruby</a></li>
<li><a href="/documentation/advanced-features/remote-file/">Remote File Task</a></li>
<li><a href="/documentation/advanced-features/ssh-kit">Remote Commands with SSHKit</li>
<li class="divider"></li> <li class="divider"></li>
<h5>Framework Extensions</h5>
<li><a href="/documentation/frameworks/ruby-on-rails/">Ruby on Rails</a></li> <h5>Plugins</h5>
<li><a href="/documentation/frameworks/bundler/">Bundler</a></li> <li><a href="https://github.com/capistrano/bundler/">Bundler</a></li>
<li><a href="/documentation/frameworks/rbenv-rvm-chruby/">Rbenv &amp; RVM &amp; chruby</a></li> <li><a href="https://github.com/capistrano/composer/">Composer</a></li>
<li><a href="/documentation/frameworks/passenger/">Passenger</a></li> <li><a href="https://github.com/capistrano/laravel/">Laravel</a></li>
<li><a href="/documentation/plugins/">Plugins</a></li> <li><a href="https://github.com/capistrano/npm/">npm</a></li>
<!--<li class="divider"></li> --> <li><a href="https://github.com/capistrano/passenger/">Phusion Passenger</a></li>
<!--<h5>Troubleshooting</h5> --> <li><a href="https://github.com/capistrano/chruby/">chruby</a></li>
<!--<li><a href="/documentation/troubleshooting/authentication/">SCM (Git) Authentication</a></li>--> <li><a href="https://github.com/capistrano/rbenv/">rbenv</a></li>
<!--<li><a href="/documentation/troubleshooting/connectivity/">Connectivity</a></li> --> <li><a href="https://github.com/capistrano/rvm/">RVM</a></li>
<!--[><li><a href="/documentation/troubleshooting/gateway-servers/">Gateway Servers</a></li><] --> <li><a href="https://github.com/capistrano/rails/">Ruby on Rails</a></li>
<!--<li><a href="/documentation/troubleshooting/agent-forwarding/">Agent Forwarding</a></li> --> <li><a href="https://github.com/capistrano/symfony/">Symfony</a></li>
<!--<li><a href="/documentation/troubleshooting/sudo-password/">`sudo` Password</a></li> --> <li><a href="/documentation/third-party-plugins/">3<sup>rd</sup> Party Plugins</a></li>
<!--<li><a href="/documentation/troubleshooting/rvm-rbenv-nvm/">RVM, `rbenv` And `nvm`</a></li> -->
<li class="divider"></li> <li class="divider"></li>
<h5>FAQ</h5> <h5>FAQ</h5>
<li><a href="/documentation/faq/why-does-something-work-in-my-ssh-session-but-not-in-capistrano/">Why Does Something Work In An SSH Session, But Not In Capistrano?</a></li> <li><a href="/documentation/faq/why-does-something-work-in-my-ssh-session-but-not-in-capistrano/">Why does something work in an SSH session, but not in Capistrano?</a></li>
<li><a href="/documentation/faq/how-can-i-get-capistrano-to-prompt-for-a-password/">How can I get Capistrano to prompt for a password?</a></li>
<li><a href="/documentation/faq/how-can-i-access-stage-configuration-variables/">How can I access stage configuration variables?</a></li> <li><a href="/documentation/faq/how-can-i-access-stage-configuration-variables/">How can I access stage configuration variables?</a></li>
<!--<li><a href="/documentation/faq/should-i-use-capistrano-to-provision-my-servers/">Should I Use Capistrano To Provision My Servers?</a></li>--> <li><a href="/documentation/faq/how-can-i-check-for-existing-remote-file/">How can I check for existing remote file?</a></li>
<li><a href="http://lee.hambley.name/2013/06/11/using-capistrano-v3-with-chef.html">Should I Use Capistrano To Provision My Servers?</a></li> <li><a href="/documentation/faq/how-can-i-get-capistrano-to-prompt-for-a-password/">How can I get Capistrano to prompt for a password?</a></li>
<!--<li class="divider"></li> --> <li><a href="http://lee.hambley.name/2013/06/11/using-capistrano-v3-with-chef.html">Should I use Capistrano to provision my servers?</a></li>
<!--<h5>Power Use-Cases</h5> -->
<!--<li><a href="/documentation/power-use-cases/integration-with-rake/">Integration With Rake</a></li> -->
<!--<li><a href="/documentation/power-use-cases/driving-tools-such-as-chef-solo/">Driving Tools Such As <em>Chef Solo</em></a></li>-->
<li class="divider"></li> <li class="divider"></li>
<h5>Legacy Documentation</h5>
<li><a href="https://github.com/capistrano/capistrano/wiki">Capistrano <h5>Legacy</h5>
v2</a></li> <li><a href="https://github.com/capistrano/capistrano/wiki">Capistrano 2 Documentation Wiki</a></li>
<li><a href="/documentation/upgrading/">Upgrading from Capistrano 2.x to 3</a></li>
<li class="divider"></li> <li class="divider"></li>
<h5>Recent Announcements</h5> <h5>Recent Announcements</h5>
{% for post in site.posts %} {% for post in site.posts %}
<li><a href="{{ post.url }}"><span class="post-date">{{ post.date | date_to_string }}</span> {{ post.title }}</a></li> <li><a href="{{ post.url }}"><span class="post-date">{{ post.date | date_to_string }}</span> {{ post.title }}</a></li>

41
_layouts/default.html
View file

@ -15,38 +15,10 @@
<link rel="stylesheet" href="/css/syntax.css"> <link rel="stylesheet" href="/css/syntax.css">
<script src="/js/vendor/custom.modernizr.js"></script> <script src="/js/vendor/custom.modernizr.js"></script>
</head> </head>
<body> <body>
{% include metrics.html %}
<script type="text/javascript">
var _gauges = _gauges || [];
(function() {
var t = document.createElement('script');
t.type = 'text/javascript';
t.async = true;
t.id = 'gauges-tracker';
t.setAttribute('data-site-id', '51c83c32613f5d7df70000bc');
t.src = '//secure.gaug.es/track.js';
var s = document.getElementsByTagName('script')[0];
s.parentNode.insertBefore(t, s);
})();
</script>
<script type="text/javascript">
setTimeout(function(){var a=document.createElement("script");
var b=document.getElementsByTagName("script")[0];
a.src=document.location.protocol+"//dnn506yrbagrg.cloudfront.net/pages/scripts/0017/6418.js?"+Math.floor(new Date().getTime()/3600000);
a.async=true;a.type="text/javascript";b.parentNode.insertBefore(a,b)}, 1);
</script>
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-41970098-1', 'capistranorb.com');
ga('send', 'pageview');
</script>
{% include header.html %} {% include header.html %}
<div class="row"> <div class="row">
@ -81,12 +53,9 @@
<script src="/js/jquery.githubRepoWidget.min.js"></script> <script src="/js/jquery.githubRepoWidget.min.js"></script>
<script src="/js/prism.js"></script> <script src="/js/prism.js"></script>
<script src="/js/prism.ruby.js"></script> <script src="/js/prism.ruby.js"></script>
<a href="https://github.com/capistrano/capistrano"><img style="position: absolute; top: 0; right: 0; border: 0;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_white_ffffff.png" alt="Fork me on GitHub"></a> <a href="https://github.com/capistrano/capistrano"><img style="position: absolute; top: 0; right: 0; border: 0;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_white_ffffff.png" alt="Fork me on GitHub"></a>
<!-- Google Tag Manager -->
<noscript> {% include google_tag_manager.html %}
<iframe src="//www.googletagmanager.com/ns.html?id=GTM-KLDBJG" height="0" width="0" style="display:none;visibility:hidden"></iframe>
</noscript>
<script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start': new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0], j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src= '//www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f); })(window,document,'script','dataLayer','GTM-KLDBJG');</script>
<!-- End Google Tag Manager -->
</body> </body>
</html> </html>

1
_layouts/table_of_contents.html
View file

@ -1 +0,0 @@
Why is this here?

4
changes.html
View file

@ -1,4 +0,0 @@
---
layout: default
title: "Recent Site Changes"
---

33
documentation/advanced-features/console/index.markdown Normal file
View file

@ -0,0 +1,33 @@
---
title: Console
layout: default
---
**Note:** Here be dragons. The console is very immature, but it's much more
cleanly architected than previous incarnations and it'll only get better from
here on in.
Execute arbitrary remote commands, to use this simply add
`require 'capistrano/console'` which will add the necessary tasks to your
environment:
``` sh
$ bundle exec cap staging console
```
Then, after setting up the server connections, this is how that might look:
``` sh
$ bundle exec cap production console
capistrano console - enter command to execute on production
production> uptime
INFO [94db8027] Running /usr/bin/env uptime on leehambley@example.com:22
DEBUG [94db8027] Command: /usr/bin/env uptime
DEBUG [94db8027] 17:11:17 up 50 days, 22:31, 1 user, load average: 0.02, 0.02, 0.05
INFO [94db8027] Finished in 0.435 seconds command successful.
production> who
INFO [9ce34809] Running /usr/bin/env who on leehambley@example.com:22
DEBUG [9ce34809] Command: /usr/bin/env who
DEBUG [9ce34809] leehambley pts/0 2013-06-13 17:11 (port-11262.pppoe.wtnet.de)
INFO [9ce34809] Finished in 0.420 seconds command successful.
```

49
documentation/advanced-features/host-and-role-filtering/index.markdown Normal file
View file

@ -0,0 +1,49 @@
---
title: Host and Role Filtering
layout: default
---
Capistrano enables the declaration of servers and roles, each of which may have properties
associated with them. Tasks are then able to use these definitions in two distinct ways:
* To determine _configurations_: typically by using the `roles()`, `release_roles()` and
`primary()` methods. Typically these are used outside the scope of the `on()` method.
* To _interact_ with remote hosts using the `on()` method
An example of the two would be to create a `/etc/krb5.conf` file containing the list of
available KDC's by using the list of servers returned by `roles(:kdc)` and then uploading
it to all client machines using `on(roles(:all)) do upload!(file) end`
A problem with this arises when _filters_ are used. Filters are designed to limit the
actual set of hosts that are used to a subset of those in the overall stage, but how
should that apply in the above case?
If the filter applies to both the _interaction_ and _configuration_ aspects, any configuration
files deployed will not be the same as those on the hosts excluded by the filters. This is
almost certainly not what is wanted, the filters should apply only to the _interactions_
ensuring that any configuration files deployed will be identical across the stage.
Another type of filtering is done by defining properties on servers and selecting on that
basis. An example of that is the 'no_release' property and it's use in the
`release_roles()` method. To distinguish these two types of filtering we name them:
* On-Filtering
Specified in the following ways:
* Via environment variables HOSTS and ROLES
* Via command line options `--hosts` and `--roles`
* Via the `:filter` variable set in a stage file
* Property-Filtering
These are specified by options passed to the `roles()` method (and implicitly in methods
like `release_roles()` and `primary()`)
To increase the utility of On-Filters they can use regular expressions:
* If the host name in a filter doesn't match `/^[-A-Za-z0-9.]+$/` (the set of valid characters
for a DNS name) then it's assumed to be a regular expression.
* Since role names are Ruby symbols they can legitimately contain any characters. To allow multiple
of them to be specified on one line we use the comma. To use a regexp for a role filter begin
and end the string with '/'. These may not contain a comma.
When filters are specified using comma separated lists, the final filter is the _union_ of
all of the components. However when multiple filters are declared the result is the
_intersection_.

19
documentation/advanced-features/ptys/index.markdown Normal file
View file

@ -0,0 +1,19 @@
There is a configuration option which asks the backend driver to ask the remote host
to assign the connection a *pty*. A *pty* is a pseudo-terminal, which in effect means
*tell the backend that this is an __interactive__ session*. This is normally a bad idea.
Most of the differences are best explained by [this page](https://github.com/sstephenson/rbenv/wiki/Unix-shell-initialization) from the author of *rbenv*.
**When Capistrano makes a connection it is a *non-login*, *non-interactive* shell.
This was not an accident!**
It's often used as a band aid to cure issues related to RVM and rbenv not loading login
and shell initialisation scripts. In these scenarios RVM and rbenv are the tools at fault,
or at least they are being used incorrectly.
Whilst, especially in the case of language runtimes (Ruby, Node, Python and friends in
particular) there is a temptation to run multiple versions in parallel on a single server
and to switch between them using environmental variables, this is an anti-pattern, and
symptomatic of bad design (e.g. you're testing a second version of Ruby in production because
your company lacks the infrastructure to test this in a staging environment).

2
documentation/faq/how-can-i-check-for-existing-remote-file/index.markdown
View file

@ -3,7 +3,7 @@ title: How can I check for existing remote file?
layout: default layout: default
--- ---
The `test` tehod is best used for file checking with bash conditionals The `test` method is best used for file checking with bash conditionals
{% highlight ruby %} {% highlight ruby %}
if test("[ -f /tmp/foo ]") if test("[ -f /tmp/foo ]")

10
documentation/frameworks/bundler/index.markdown
View file

@ -1,10 +0,0 @@
---
title: Bundler
layout: default
---
Capistrano 3.x has moved out Bundler integration into the gem called `capistrano-bundler`.
You don't need anything except `require 'capistrano/bundler'` to enable it, although check the project page with README if you wish to customize bundle options.
<div class="github-widget" data-repo="capistrano/bundler"></div>

11
documentation/frameworks/passenger/index.markdown
View file

@ -1,11 +0,0 @@
---
title: Passenger
layout: default
---
Capistrano 3.x does not restart your application by default. You need to add a task to do this `after deploy:publishing`.
If you're using passenger, this gem has you covered. All you need to do is `require 'capistrano/passenger' in your Capfile.
Checkout the README to learn how to customize the timing of restarts. By default, the deployment will wait 5 seconds between server restarts so all your servers don't shut off at once.
<div class="github-widget" data-repo="capistrano/passenger"></div>

17
documentation/frameworks/rbenv-rvm-chruby/index.markdown
View file

@ -1,17 +0,0 @@
---
title: Rbenv & RVM & Chruby
layout: default
---
Capistrano 3.x comes with official support of most common ruby version managers: Rbenv, RVM and Chruby.
Basic installation includes `require 'capistrano/rbenv'` (or `capistrano/rvm` / `capistrano/chruby`) and defining `set :rbenv_ruby_version, '2.0.0-p247'`, or `rvm_ruby_version` / `chruby_ruby`.
Capistrano is not taking responsibility to install rubies, so on the servers you are deploying to, you will have to manually install the proper ruby and (optionally) create the gemset.
Check README of each gem if you want to customize other options like user or system-wide installation type.
<div class="github-widget" data-repo="capistrano/rbenv"></div>
<div class="github-widget" data-repo="capistrano/rvm"></div>
<div class="github-widget" data-repo="capistrano/chruby"></div>

24
documentation/frameworks/ruby-on-rails/index.markdown
View file

@ -1,24 +0,0 @@
---
title: Ruby on Rails
layout: default
---
**Note:** The Ruby on Rails tasks target the most recent Ruby on Rails
version, and as such might be unsuitable for you, please test these recipes in
your staging environment before deploying them to production!
### Capistrano::Rails
The official Gem for Capistrano-Rails is named `capistrano-rails`, and one can
simply define this in one's Rails project's `Gemfile`, it will depend on a
suitably new version of Capistrano.
The
[`README`](https://github.com/capistrano/rails/blob/master/README.md)
for the Capistrano::Rails explains more than enough, sufficed to say that it
adds appropriate hooks for database migrations and asset compilation at the
appropriate times.
<div class="github-widget" data-repo="capistrano/rails"></div>

55
documentation/getting-started/before-after/index.markdown Normal file
View file

@ -0,0 +1,55 @@
---
title: Before / After Hooks
layout: default
---
Where calling on the same task name, executed in order of inclusion
``` ruby
# call an existing task
before :starting, :ensure_user
after :finishing, :notify
# or define in block
before :starting, :ensure_user do
#
end
after :finishing, :notify do
#
end
```
If it makes sense for your use case (often, that means *generating a file*)
the Rake prerequisite mechanism can be used:
``` ruby
desc "Create Important File"
file 'important.txt' do |t|
sh "touch #{t.name}"
end
desc "Upload Important File"
task :upload => 'important.txt' do |t|
on roles(:all) do
upload!(t.prerequisites.first, '/tmp')
end
end
```
The final way to call out to other tasks is to simply `invoke()` them:
``` ruby
namespace :example do
task :one do
on roles(:all) { info "One" }
end
task :two do
invoke "example:one"
on roles(:all) { info "Two" }
end
end
```
This method is widely used.

22
documentation/getting-started/configuration/index.markdown Normal file
View file

@ -0,0 +1,22 @@
---
title: Configuration
layout: default
---
## Configuration
The following variables are settable:
| Variable Name | Description | Notes |
|:---------------------:|----------------------------------------------------------------------|-----------------------------------------------------------------|
| `:repo_url` | The URL of your scm repository (git, hg, svn) | file://, https://, ssh://, or svn+ssh:// are all supported |
| `:repo_tree` | The subtree of the scm repository to deploy (git, hg) | Only implemented for git and hg repos. Extract just this tree |
| `: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. |
| `:scm` | The source control system used | `:git`, `:hg`, `:svn` are currently supported |
| `: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). |
__Support removed__ for following variables:
| Variable Name | Description | Notes |
|:---------------------:|---------------------------------------------------------------------|-----------------------------------------------------------------|
| `: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. |

35
documentation/getting-started/local-tasks/index.markdown Normal file
View file

@ -0,0 +1,35 @@
---
title: Local Tasks
layout: default
---
Local tasks can be run by replacing `on` with `run_locally`:
```ruby
desc 'Notify service of deployment'
task :notify do
run_locally do
with rails_env: :development do
rake 'service:notify'
end
end
end
```
Of course, you can always just use standard ruby syntax to run things locally:
```ruby
desc 'Notify service of deployment'
task :notify do
%x('RAILS_ENV=development bundle exec rake "service:notify"')
end
```
Alternatively you could use the rake syntax:
```ruby
desc "Notify service of deployment"
task :notify do
sh 'RAILS_ENV=development bundle exec rake "service:notify"'
end
```

11
documentation/getting-started/password-authentication/index.markdown Normal file
View file

@ -0,0 +1,11 @@
---
title: Password Authentication
layout: default
---
Password authentication can be done via `set` and `ask` in your deploy environment file (e.g.: config/deploy/production.rb)
```ruby
set :password, ask('Server password', nil)
server 'server.domain.com', user: 'ssh_user_name', port: 22, password: fetch(:password), roles: %w{web app db}
```

1
documentation/getting-started/rollbacks/index.markdown
View file

@ -4,4 +4,3 @@ layout: default
--- ---
**Missing Content** **Missing Content**

19
documentation/getting-started/tasks/index.markdown Normal file
View file

@ -0,0 +1,19 @@
``` ruby
server 'example.com', roles: [:web, :app]
server 'example.org', roles: [:db, :workers]
desc "Report Uptimes"
task :uptime do
on roles(:all) do |host|
execute :any_command, "with args", :here, "and here"
info "Host #{host} (#{host.roles.to_a.join(', ')}):\t#{capture(:uptime)}"
end
end
```
**Note**:
**tl;dr**: `execute(:bundle, :install)` and `execute('bundle install')` don't behave identically!
`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.
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.

22
documentation/getting-started/user-input/index.markdown Normal file
View file

@ -0,0 +1,22 @@
---
title: User Input
layout: default
---
``` ruby
desc "Ask about breakfast"
task :breakfast do
ask(:breakfast, "pancakes")
on roles(:all) do |h|
execute "echo \"$(whoami) wants #{fetch(:breakfast)} for breakfast!\""
end
end
```
Perfect, who needs telephones.
When using `ask` to get user input, you can pass `echo: false` to prevent the input from being displayed:
```ruby
ask(:database_password, "default", echo: false)
```

7
documentation/plugins/index.markdown → documentation/third-party-plugins/index.markdown
View file

@ -1,9 +1,10 @@
--- ---
title: Plugins title: 3rd Party Plugins
layout: default layout: default
--- ---
Here are some Capistrano plugins you might find useful. Here are some Capistrano plugins you might find useful.
This list is neither complete nor audited in any way.
<div class="github-widget" data-repo="capistrano-plugins/capistrano-postgresql"></div> <div class="github-widget" data-repo="capistrano-plugins/capistrano-postgresql"></div>
@ -13,6 +14,8 @@ Here are some Capistrano plugins you might find useful.
<div class="github-widget" data-repo="capistrano-plugins/capistrano-safe-deploy-to"></div> <div class="github-widget" data-repo="capistrano-plugins/capistrano-safe-deploy-to"></div>
<div class="github-widget" data-repo="capistrano-plugins/capistrano-ssh-doctor"></div>
<div class="github-widget" data-repo="scottsuch/capistrano-graphite"></div> <div class="github-widget" data-repo="scottsuch/capistrano-graphite"></div>
<div class="github-widget" data-repo="capistrano-plugins/capistrano-ssh-doctor"></div> <div class="github-widget" data-repo="dei79/capistrano-rails-collection"></div>

4
documentation/upgrading/index.markdown
View file

@ -7,7 +7,7 @@ layout: default
Update your Gemfile: `gem 'capistrano', '~> 3.0', require: false, group: :development` Update your Gemfile: `gem 'capistrano', '~> 3.0', require: false, group: :development`
If you deploy Rails, you wil also need `capistrano-rails` and `capistrano-bundler` gems (Rails and Bundler integrations were moved out from Capistrano 3.x). If you deploy Rails, you wil also need `capistrano-rails` and `capistrano-bundler` gems (Rails and Bundler integrations were moved out from Capistrano 3).
{% highlight ruby %} {% highlight ruby %}
group :development do group :development do
gem 'capistrano-rails', '~> 1.1', require: false gem 'capistrano-rails', '~> 1.1', require: false
@ -41,7 +41,7 @@ layout: default
{% endhighlight %} {% endhighlight %}
3. 3.
Capistrano 3.x is multistage by default, so you will have `config/deploy/production.rb` and `config/deploy/staging.rb` right after capifying. Capistrano 3 is multistage by default, so you will have `config/deploy/production.rb` and `config/deploy/staging.rb` right after capifying.
If you need only one stage, remove these files and declare stage (for example `production`) and servers in `config/deploy.rb`. If you need only one stage, remove these files and declare stage (for example `production`) and servers in `config/deploy.rb`.
4. 4.

3
index.markdown
View file

@ -29,5 +29,4 @@ extended to support them.
### Source Code ### Source Code
<div class="github-widget" data-repo="capistrano/capistrano"></div> <div class="github-widget" data-repo="capistrano/capistrano"></div>
<div class="github-widget" data-repo="capistrano/rails"></div> <div class="github-widget" data-repo="capistrano/capistrano.github.io"></div>
<div class="github-widget" data-repo="capistrano/documentation"></div>