mirror of
https://github.com/capistrano/capistrano
synced 2023-03-27 23:21:18 -04:00
Merge pull request #110 from Kriechi/add-readme-sections
Add readme sections
This commit is contained in:
Lee Hambley
commit
c2e80bb804
24 changed files with 329 additions and 149 deletions
|
|
@ -5,6 +5,4 @@ lsi: false
|
|||
markdown: redcarpet
|
||||
redcarpet:
|
||||
extensions: ["no_intra_emphasis", "fenced_code_blocks", "autolink", "tables", "with_toc_data"]
|
||||
table_of_contents:
|
||||
dirs: [documentation]
|
||||
exclude: ["Gemfile", "Gemfile.lock", "README.md"]
|
||||
|
|
|
|||
6
_includes/google_tag_manager.html
Normal file
6
_includes/google_tag_manager.html
Normal 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 -->
|
||||
|
|
@ -1,59 +1,67 @@
|
|||
<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 class="divider"></li>
|
||||
|
||||
<h5>Overview</h5>
|
||||
<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>
|
||||
|
||||
<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="/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/authentication-and-authorisation/">Authentication & 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/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 & Authorisation</a></li>
|
||||
<li><a href="/documentation/getting-started/password-authentication/">Password Authentication</a></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>
|
||||
<h5>Framework Extensions</h5>
|
||||
<li><a href="/documentation/frameworks/ruby-on-rails/">Ruby on Rails</a></li>
|
||||
<li><a href="/documentation/frameworks/bundler/">Bundler</a></li>
|
||||
<li><a href="/documentation/frameworks/rbenv-rvm-chruby/">Rbenv & RVM & chruby</a></li>
|
||||
<li><a href="/documentation/frameworks/passenger/">Passenger</a></li>
|
||||
<li><a href="/documentation/plugins/">Plugins</a></li>
|
||||
<!--<li class="divider"></li> -->
|
||||
<!--<h5>Troubleshooting</h5> -->
|
||||
<!--<li><a href="/documentation/troubleshooting/authentication/">SCM (Git) Authentication</a></li>-->
|
||||
<!--<li><a href="/documentation/troubleshooting/connectivity/">Connectivity</a></li> -->
|
||||
<!--[><li><a href="/documentation/troubleshooting/gateway-servers/">Gateway Servers</a></li><] -->
|
||||
<!--<li><a href="/documentation/troubleshooting/agent-forwarding/">Agent Forwarding</a></li> -->
|
||||
<!--<li><a href="/documentation/troubleshooting/sudo-password/">`sudo` Password</a></li> -->
|
||||
<!--<li><a href="/documentation/troubleshooting/rvm-rbenv-nvm/">RVM, `rbenv` And `nvm`</a></li> -->
|
||||
|
||||
<h5>Plugins</h5>
|
||||
<li><a href="https://github.com/capistrano/bundler/">Bundler</a></li>
|
||||
<li><a href="https://github.com/capistrano/composer/">Composer</a></li>
|
||||
<li><a href="https://github.com/capistrano/laravel/">Laravel</a></li>
|
||||
<li><a href="https://github.com/capistrano/npm/">npm</a></li>
|
||||
<li><a href="https://github.com/capistrano/passenger/">Phusion Passenger</a></li>
|
||||
<li><a href="https://github.com/capistrano/chruby/">chruby</a></li>
|
||||
<li><a href="https://github.com/capistrano/rbenv/">rbenv</a></li>
|
||||
<li><a href="https://github.com/capistrano/rvm/">RVM</a></li>
|
||||
<li><a href="https://github.com/capistrano/rails/">Ruby on Rails</a></li>
|
||||
<li><a href="https://github.com/capistrano/symfony/">Symfony</a></li>
|
||||
<li><a href="/documentation/third-party-plugins/">3<sup>rd</sup> Party Plugins</a></li>
|
||||
<li class="divider"></li>
|
||||
|
||||
<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/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/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-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="http://lee.hambley.name/2013/06/11/using-capistrano-v3-with-chef.html">Should I Use Capistrano To Provision My Servers?</a></li>
|
||||
<!--<li class="divider"></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><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="/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="http://lee.hambley.name/2013/06/11/using-capistrano-v3-with-chef.html">Should I use Capistrano to provision my servers?</a></li>
|
||||
<li class="divider"></li>
|
||||
<h5>Legacy Documentation</h5>
|
||||
<li><a href="https://github.com/capistrano/capistrano/wiki">Capistrano
|
||||
v2</a></li>
|
||||
|
||||
<h5>Legacy</h5>
|
||||
<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>
|
||||
|
||||
<h5>Recent Announcements</h5>
|
||||
{% for post in site.posts %}
|
||||
<li><a href="{{ post.url }}"><span class="post-date">{{ post.date | date_to_string }}</span> {{ post.title }}</a></li>
|
||||
|
|
|
|||
|
|
@ -15,38 +15,10 @@
|
|||
<link rel="stylesheet" href="/css/syntax.css">
|
||||
<script src="/js/vendor/custom.modernizr.js"></script>
|
||||
</head>
|
||||
|
||||
<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 %}
|
||||
|
||||
<div class="row">
|
||||
|
|
@ -81,12 +53,9 @@
|
|||
<script src="/js/jquery.githubRepoWidget.min.js"></script>
|
||||
<script src="/js/prism.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>
|
||||
<!-- 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 -->
|
||||
|
||||
{% include google_tag_manager.html %}
|
||||
</body>
|
||||
</html>
|
||||
|
|
|
|||
|
|
@ -1 +0,0 @@
|
|||
Why is this here?
|
||||
|
|
@ -1,4 +0,0 @@
|
|||
---
|
||||
layout: default
|
||||
title: "Recent Site Changes"
|
||||
---
|
||||
33
documentation/advanced-features/console/index.markdown
Normal file
33
documentation/advanced-features/console/index.markdown
Normal 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.
|
||||
```
|
||||
|
|
@ -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
19
documentation/advanced-features/ptys/index.markdown
Normal 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).
|
||||
|
|
@ -3,7 +3,7 @@ title: How can I check for existing remote file?
|
|||
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 %}
|
||||
if test("[ -f /tmp/foo ]")
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
|
||||
|
|
@ -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>
|
||||
|
||||
|
|
@ -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>
|
||||
|
||||
|
|
@ -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
55
documentation/getting-started/before-after/index.markdown
Normal 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
22
documentation/getting-started/configuration/index.markdown
Normal 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
35
documentation/getting-started/local-tasks/index.markdown
Normal 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
|
||||
```
|
||||
|
|
@ -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}
|
||||
```
|
||||
|
|
@ -4,4 +4,3 @@ layout: default
|
|||
---
|
||||
|
||||
**Missing Content**
|
||||
|
||||
|
|
|
|||
19
documentation/getting-started/tasks/index.markdown
Normal file
19
documentation/getting-started/tasks/index.markdown
Normal 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
22
documentation/getting-started/user-input/index.markdown
Normal 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)
|
||||
```
|
||||
|
|
@ -1,9 +1,10 @@
|
|||
---
|
||||
title: Plugins
|
||||
title: 3rd Party Plugins
|
||||
layout: default
|
||||
---
|
||||
|
||||
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>
|
||||
|
||||
|
|
@ -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-ssh-doctor"></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>
|
||||
|
|
@ -7,7 +7,7 @@ layout: default
|
|||
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 %}
|
||||
group :development do
|
||||
gem 'capistrano-rails', '~> 1.1', require: false
|
||||
|
|
@ -41,7 +41,7 @@ layout: default
|
|||
{% endhighlight %}
|
||||
|
||||
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`.
|
||||
|
||||
4.
|
||||
|
|
|
|||
|
|
@ -29,5 +29,4 @@ extended to support them.
|
|||
### Source Code
|
||||
|
||||
<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/documentation"></div>
|
||||
<div class="github-widget" data-repo="capistrano/capistrano.github.io"></div>
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue