{% endhighlight %}
- * `current` is a symlink pointing to the latest release. This symlink is updated at the end of a successful deployment. If the deployment fails in any step the `current` symlink still points to the old release.
- * `releases` holds all deployments in a timestamped folder. These folders are the target of the `current` symlink.
- * `repo` holds the version control system configured. In case of a git repository the content will be a raw git repository (e.g. objects, refs, etc.).
- * `revisions.log` is used to log every deploy or rollback. Each entry is timestamped and the executing user (username from local machine) is listed. Depending on your VCS data like branchnames or revision numbers are listed as well.
- * `shared` contains the `linked_files` and `linked_dirs` which are symlinked into each release. This data persists across deployments and releases. It should be used for things like database configuration files and static and persistent user storage handed over from one release to the next.
+* `current` is a symlink pointing to the latest release. This symlink is
+updated at the end of a successful deployment. If the deployment fails in any
+step the `current` symlink still points to the old release.
+* `releases` holds all deployments in a timestamped folder. These folders are
+the target of the `current` symlink.
-The application is completely contained within the path of `:deploy_to`. If you plan on deploying multiple applications to the same server, simply choose a different `:deploy_to` path.
+* `repo` holds the version control system configured. In case of a git
+repository the content will be a raw git repository (e.g. objects, refs,
+etc.).
+
+* `revisions.log` is used to log every deploy or rollback. Each entry is
+timestamped and the executing user (username from local machine) is listed.
+Depending on your VCS data like branchnames or revision numbers are listed as
+well.
+
+* `shared` contains the `linked_files` and `linked_dirs` which are symlinked
+into each release. This data persists across deployments and releases. It
+should be used for things like database configuration files and static and
+persistent user storage handed over from one release to the next.
+
+The application is completely contained within the path of `:deploy_to`. If
+you plan on deploying multiple applications to the same server, simply choose
+a different `:deploy_to` path.
diff --git a/documentation/overview/introductory-demo-video/index.markdown b/documentation/overview/introductory-demo-video/index.markdown
deleted file mode 100644
index 63577cd9..00000000
--- a/documentation/overview/introductory-demo-video/index.markdown
+++ /dev/null
@@ -1,36 +0,0 @@
----
-title: Introductory Demo Video
-layout: default
----
-
-The video below was filmed on Mac OSX 10.8 using a more-or-less standard shell
-without much previous setup.
-
-It covers using Capistrano to install an example Rails project on a previously
-unprepared server, covering all aspects of Github access, as well as
-privisioning the server using *Chef Solo* and Capistrano with *Rake*.
-
-#### Show Notes
-
-The *Chef Solo* recipes can be reached at [this repository at
-Github][capistrano-chef-solo-example-recipes], they rely on a fairly new
-version of *Chef Solo*, spefically any including the results of [this
-ticket][chef-issue-3365]. The aforementioned *Chef* issue adds environment
-support to *Chef Solo*.
-
-The provisioning can also be done using any other mechanism, it's generally
-accepted however that there's not much point in automising your deploys,
-unless you are also automating provisioning of your servers for a known,
-consistent state.
-
-Using `sudo` with any deployment can be tricky, so it's better to avoid it.
-Rebooting services without `sudo` is typically the first place people run into
-trouble using Capistrano. The [trouble shooting page for `sudo`
-problems][troubleshooting-sudo-password] may help.
-
-**Note:** Some long sequences have been shortened (nobody needs to sit and watch me
-sitting and watching Ruby compile, for example!)
-
---
-[chef-issue-3365]: https://github.com/opscode/chef/pull/359
-[troubleshooting-sudo-password]: /troubleshooting/sudo-password/
diff --git a/documentation/overview/what-is-capistrano/index.markdown b/documentation/overview/what-is-capistrano/index.markdown
index 989ee574..5afa2c20 100644
--- a/documentation/overview/what-is-capistrano/index.markdown
+++ b/documentation/overview/what-is-capistrano/index.markdown
@@ -23,7 +23,7 @@ Ruby software to form part of a larger tool.
#### What does it look like?
{% highlight bash %}
- me@localhost $ cap staging deploy
+me@localhost $ cap staging deploy
{% endhighlight %}
@@ -99,49 +99,48 @@ There's lots of cool stuff in the Capistrano toy box:
* A sane, expressive API:
{% highlight ruby %}
- desc "Show off the API"
- task :ditty do
+desc "Show off the API"
+task :ditty do
- on roles(:all) do |host|
- # Capture output from the remote host, and re-use it
- # we can reflect on the `host` object passed to the block
- # and use the `info` logger method to benefit from the
- # output formatter that is selected.
- uptime = capture('uptime')
- if host.roles.include?(:web)
- info "Your webserver #{host} has uptime: #{uptime}"
- end
+ on roles(:all) do |host|
+ # Capture output from the remote host, and re-use it
+ # we can reflect on the `host` object passed to the block
+ # and use the `info` logger method to benefit from the
+ # output formatter that is selected.
+ uptime = capture('uptime')
+ if host.roles.include?(:web)
+ info "Your webserver #{host} has uptime: #{uptime}"
end
-
- on roles(:app) do
- # We can set environmental variables for the duration of a block
- # and move the process into a directoy, executing arbitrary tasks
- # such as letting Rails do some heavy lifting.
- with({:rails_env => :production}) do
- within('/var/www/my/rails/app') do
- execute :rails, :runner, 'MyModel.something'
- end
- end
- end
-
- on roles(:db) do
- # We can even switch users, provided we have support on the remote
- # server for switching to that user without being prompted for a
- # passphrase.
- as 'postgres' do
- widgets = capture "echo 'SELECT * FROM widgets;' | psql my_database"
- if widgets.to_i < 50
- warn "There are fewer than 50 widgets in the database on #{host}!"
- end
- end
- end
-
- on roles(:all) do
- # We can even use `test` the way the Unix gods intended
- if test("[ -d /some/directory ]")
- info "Phew, it's ok, the directory exists!"
- end
- end
-
end
+
+ on roles(:app) do
+ # We can set environmental variables for the duration of a block
+ # and move the process into a directoy, executing arbitrary tasks
+ # such as letting Rails do some heavy lifting.
+ with({:rails_env => :production}) do
+ within('/var/www/my/rails/app') do
+ execute :rails, :runner, 'MyModel.something'
+ end
+ end
+ end
+
+ on roles(:db) do
+ # We can even switch users, provided we have support on the remote
+ # server for switching to that user without being prompted for a
+ # passphrase.
+ as 'postgres' do
+ widgets = capture "echo 'SELECT * FROM widgets;' | psql my_database"
+ if widgets.to_i < 50
+ warn "There are fewer than 50 widgets in the database on #{host}!"
+ end
+ end
+ end
+
+ on roles(:all) do
+ # We can even use `test` the way the Unix gods intended
+ if test("[ -d /some/directory ]")
+ info "Phew, it's ok, the directory exists!"
+ end
+ end
+end
{% endhighlight %}
diff --git a/documentation/upgrading/index.markdown b/documentation/upgrading/index.markdown
index 2005abc6..6f4f44ce 100644
--- a/documentation/upgrading/index.markdown
+++ b/documentation/upgrading/index.markdown
@@ -4,87 +4,86 @@ layout: default
---
1.
- 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).
- {% highlight ruby %}
- group :development do
- gem 'capistrano-rails', '~> 1.1', require: false
- gem 'capistrano-bundler', '~> 1.1', require: false
- end
- {% endhighlight %}
+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
+ gem 'capistrano-bundler', '~> 1.1', require: false
+end
+{% endhighlight %}
You can add idiomatic support for your preferred ruby version manager: rvm, rbenv, chruby.
- {% highlight ruby %}
- group :development do
- gem 'capistrano-rvm', '~> 0.1', require: false
- gem 'capistrano-rbenv', '~> 2.0', require: false
- gem 'capistrano-chruby', github: 'capistrano/chruby', require: false
- end
- {% endhighlight %}
+{% highlight ruby %}
+group :development do
+ gem 'capistrano-rvm', '~> 0.1', require: false
+ gem 'capistrano-rbenv', '~> 2.0', require: false
+ gem 'capistrano-chruby', github: 'capistrano/chruby', require: false
+end
+{% endhighlight %}
2.
- We recommend to capify the project from scratch and move definitions from old to new configs then.
+We recommend to capify the project from scratch and move definitions from old to new configs then.
- {% highlight bash %}
- mkdir old_cap
- mv Capfile old_cap
- mv config/deploy.rb old_cap
- mv config/deploy/ old_cap # --> only for multistage setups
- {% endhighlight %}
+{% highlight bash %}
+mkdir old_cap
+mv Capfile old_cap
+mv config/deploy.rb old_cap
+mv config/deploy/ old_cap # --> only for multistage setups
+{% endhighlight %}
- It's time to capify:
+It's time to capify:
- {% highlight bash %}
- cap install
- {% endhighlight %}
+{% highlight bash %}
+cap install
+{% endhighlight %}
3.
- Capistrano 3 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.
- Update `config/deploy/production.rb` and `config/deploy/staging.rb` to have relevant data there. You may also want to add more stages from old configs (`old_cap/deploy/`).
+Update `config/deploy/production.rb` and `config/deploy/staging.rb` to have relevant data there. You may also want to add more stages from old configs (`old_cap/deploy/`).
5.
- If you had a gateway server set doing `set :gateway, "www.capify.org"` you should upgrade to
+If you had a gateway server set doing `set :gateway, "www.capify.org"` you should upgrade to
- {% highlight ruby %}
- require 'net/ssh/proxy/command'
+{% highlight ruby %}
+require 'net/ssh/proxy/command'
- set :ssh_options, proxy: Net::SSH::Proxy::Command.new('ssh mygateway.com -W %h:%p')
- {% endhighlight %}
+set :ssh_options, proxy: Net::SSH::Proxy::Command.new('ssh mygateway.com -W %h:%p')
+{% endhighlight %}
- Or the per-server `ssh_options` equivalent.
+Or the per-server `ssh_options` equivalent.
6.
- Now you need to refactor your old `deploy.rb` (also `Capfile`, but in most of cases developers didn't change it in Capistrano 2.x). Move parameters (like `set :deploy_to, "/home/deploy/#{application}"` or `set :keep_releases, 4`) to `config/deploy.rb` and tasks to `Capfile`.
+Now you need to refactor your old `deploy.rb` (also `Capfile`, but in most of cases developers didn't change it in Capistrano 2.x). Move parameters (like `set :deploy_to, "/home/deploy/#{application}"` or `set :keep_releases, 4`) to `config/deploy.rb` and tasks to `Capfile`.
- *Important: `repository` option was renamed to `repo_url`; `default_environment` option was renamed to `default_env`.*
+*Important: `repository` option was renamed to `repo_url`; `default_environment` option was renamed to `default_env`.*
-
- Notice that some parameters are not necessary anymore: `use_sudo`, `normalize_asset_timestamps`.
+Notice that some parameters are not necessary anymore: `use_sudo`, `normalize_asset_timestamps`.
7.
- If you didn't use `deploy_to` before and deployed to `/u/apps/your_app_name`, you need one more change. Now default deploy path is `/var/www/app_name` and your config will be broken after upgrade. Just declare custom `deploy_to` option:
+If you didn't use `deploy_to` before and deployed to `/u/apps/your_app_name`, you need one more change. Now default deploy path is `/var/www/app_name` and your config will be broken after upgrade. Just declare custom `deploy_to` option:
- {% highlight ruby %}
- set :deploy_to, "/u/apps/#{fetch(:application)}"
- {% endhighlight %}
+{% highlight ruby %}
+set :deploy_to, "/u/apps/#{fetch(:application)}"
+{% endhighlight %}
- But in advance, `/u/apps` is not the best place to store apps and we advice you to change it later.
+But in advance, `/u/apps` is not the best place to store apps and we advice you to change it later.
8.
- Keep editing Capfile and uncomment addons you need, such as rbenv/rvm, bundler or rails.
- {% highlight ruby %}
- require 'capistrano/rails'
- require 'capistrano/bundler'
- require 'capistrano/rbenv'
- {% endhighlight %}
+Keep editing Capfile and uncomment addons you need, such as rbenv/rvm, bundler or rails.
+{% highlight ruby %}
+require 'capistrano/rails'
+require 'capistrano/bundler'
+require 'capistrano/rbenv'
+{% endhighlight %}
9.
- Yay! Try to deploy with your new config set. If you discover any missing info in this upgrade guide, you're welcome to contribute to it.
+Yay! Try to deploy with your new config set. If you discover any missing info in this upgrade guide, you're welcome to contribute to it.
# General recommendations
@@ -93,22 +92,22 @@ layout: default
Instead of:
{% highlight ruby %}
- run <<-CMD.compact
- cd -- #{latest_release} &&
- RAILS_ENV=#{rails_env.to_s.shellescape} #{asset_env} #{rake} assets:precompile
- CMD
+run <<-CMD.compact
+ cd -- #{latest_release} &&
+ RAILS_ENV=#{rails_env.to_s.shellescape} #{asset_env} #{rake} assets:precompile
+CMD
{% endhighlight %}
It's better to use:
{% highlight ruby %}
- on roles :all do
- within fetch(:latest_release_directory) do
- with rails_env: fetch(:rails_env) do
- execute :rake, 'assets:precompile'
- end
+on roles :all do
+ within fetch(:latest_release_directory) do
+ with rails_env: fetch(:rails_env) do
+ execute :rake, 'assets:precompile'
end
end
+end
{% endhighlight %}
Note: 'within' blocks are required to be wrapped in an 'on' block for the dsl to recognize it
@@ -116,11 +115,11 @@ Note: 'within' blocks are required to be wrapped in an 'on' block for the dsl to
You may only have one 'with' block per call. If you need more than one env set, use the syntax in the 'with' block arg like this (pass it a map):
{% highlight ruby %}
- on roles :all do
- within fetch(:latest_release_directory) do
- with rails_env: fetch(:rails_env), rails_relative_url_root: '/home' do
- execute :rake, 'assets:precompile', env: {rails_env: fetch(:rails_env), rails_relative_url_root: ''}
- end
+on roles :all do
+ within fetch(:latest_release_directory) do
+ with rails_env: fetch(:rails_env), rails_relative_url_root: '/home' do
+ execute :rake, 'assets:precompile', env: {rails_env: fetch(:rails_env), rails_relative_url_root: ''}
end
end
+end
{% endhighlight %}