From c79b3613cdc108f169be01818fb2df9734745104 Mon Sep 17 00:00:00 2001 From: Nick Townsend Date: Sat, 7 Feb 2015 09:55:09 -0800 Subject: [PATCH] Change all highlights to use back-ticks --- .../capistrano-pure-ruby/index.markdown | 4 +- .../advanced-features/console/index.markdown | 8 +-- .../host-filtering/index.markdown | 12 ++-- .../index.markdown | 16 ++--- .../remote-file/index.markdown | 4 +- .../role-filtering/index.markdown | 12 ++-- .../advanced-features/ssh-kit/index.markdown | 4 +- .../index.markdown | 20 +++--- .../index.markdown | 4 +- .../index.markdown | 4 +- .../index.markdown | 16 ++--- .../index.markdown | 68 +++++++++---------- .../before-after/index.markdown | 12 ++-- .../getting-started/cold-start/index.markdown | 40 +++++------ .../configuration/index.markdown | 8 +-- .../getting-started/flow/index.markdown | 20 +++--- .../installation/index.markdown | 20 +++--- .../local-tasks/index.markdown | 12 ++-- .../getting-started/structure/index.markdown | 8 +-- .../getting-started/tasks/index.markdown | 4 +- .../getting-started/user-input/index.markdown | 16 ++--- .../what-is-capistrano/index.markdown | 8 +-- documentation/upgrading/index.markdown | 40 +++++------ index.markdown | 4 +- 24 files changed, 182 insertions(+), 182 deletions(-) diff --git a/documentation/advanced-features/capistrano-pure-ruby/index.markdown b/documentation/advanced-features/capistrano-pure-ruby/index.markdown index 72fc4745..68438922 100644 --- a/documentation/advanced-features/capistrano-pure-ruby/index.markdown +++ b/documentation/advanced-features/capistrano-pure-ruby/index.markdown @@ -7,7 +7,7 @@ Instead of building a config folder and deploy, you may want to programmatically set everything in a single ruby script. This could be done as follows: -{% highlight ruby %} +```ruby require 'capistrano/all' stages = "production" @@ -23,7 +23,7 @@ Dir.glob('capistrano/tasks/*.rake').each { |r| import r } Capistrano::Application.invoke("production") Capistrano::Application.invoke("deploy") -{% endhighlight%} +``` Note that the require order is important as the stage needs to be set before you load setup and deploy. diff --git a/documentation/advanced-features/console/index.markdown b/documentation/advanced-features/console/index.markdown index 3e5117ad..907413eb 100644 --- a/documentation/advanced-features/console/index.markdown +++ b/documentation/advanced-features/console/index.markdown @@ -11,13 +11,13 @@ Execute arbitrary remote commands, to use this simply add `require 'capistrano/console'` which will add the necessary tasks to your environment: -{% highlight bash %} +```bash $ bundle exec cap staging console -{% endhighlight %} +``` Then, after setting up the server connections, this is how that might look: -{% highlight bash %} +```bash $ bundle exec cap production console capistrano console - enter command to execute on production production> uptime @@ -30,4 +30,4 @@ production> who 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. -{% endhighlight %} +``` diff --git a/documentation/advanced-features/host-filtering/index.markdown b/documentation/advanced-features/host-filtering/index.markdown index 4ff22bf9..5e589752 100644 --- a/documentation/advanced-features/host-filtering/index.markdown +++ b/documentation/advanced-features/host-filtering/index.markdown @@ -26,9 +26,9 @@ There are three ways to specify the host filter. Capistrano will read the host filter from the environment variable `HOSTS` if it is set. You can set it inline: -{% highlight bash %} +```bash HOSTS=server1,server2 cap production deploy -{% endhighlight %} +``` Specify multiple hosts by separating them with a comma. @@ -37,9 +37,9 @@ Specify multiple hosts by separating them with a comma. You can set the host filter inside your deploy configuration. For example, you can set the following inside `config/deploy.rb`: -{% highlight ruby %} +```ruby set :filter, :host => %w{server1 server2} -{% endhighlight %} +``` Note that you specify the filter as an array rather than as a comma-separated list of servers when using this method. @@ -49,9 +49,9 @@ list of servers when using this method. In a similar way to using the environment variable, you can set the role filter by specifying it as a command line argument to `cap`: -{% highlight bash %} +```bash cap --hosts=server1,server2 production deploy -{% endhighlight %} +``` Like the environment variable method, specify multiple servers by separating them with a comma. diff --git a/documentation/advanced-features/overriding-capistrano-tasks/index.markdown b/documentation/advanced-features/overriding-capistrano-tasks/index.markdown index 4da973a7..316696cf 100644 --- a/documentation/advanced-features/overriding-capistrano-tasks/index.markdown +++ b/documentation/advanced-features/overriding-capistrano-tasks/index.markdown @@ -7,7 +7,7 @@ When re-defining a task in Capistrano v2, the original task was replaced. The Rake DSL on which Capistrano v3 is built is additive however, which means that given the following definitions -{% highlight ruby %} +```ruby task :foo do puts "foo" end @@ -15,7 +15,7 @@ end task :foo do puts "bar" end -{% endhighlight %} +``` Will print both `foo` and `bar`. @@ -32,11 +32,11 @@ for a task) is probably not what you want, though. Let's say, for example, that you want to re-define the `deploy:revert_release` task, which is defined as follows: -{% highlight ruby %} +```ruby task :revert_release => :rollback_release_path do # ... end -{% endhighlight %} +``` Calling `clear` on this task and then re-defining it results in `rollback_release_path` never being called, thus breaking rollback behavior. @@ -45,7 +45,7 @@ Under most circumstances, you will simply want to use `clear_actions`, which removes the specified task's behaviour, but does not alter it's dependencies or comments: -{% highlight ruby %} +```ruby task :init do puts "init" end @@ -58,13 +58,13 @@ Rake::Task["foo"].clear_actions task :foo do puts "bar" end -{% endhighlight %} +``` Running the `foo` task will print -{% highlight ruby %} +```ruby init bar -{% endhighlight %} +``` --- diff --git a/documentation/advanced-features/remote-file/index.markdown b/documentation/advanced-features/remote-file/index.markdown index 578787ec..cab8b16e 100644 --- a/documentation/advanced-features/remote-file/index.markdown +++ b/documentation/advanced-features/remote-file/index.markdown @@ -8,7 +8,7 @@ The `remote_file` task is allowing the existence of a remote file to be set as a As an example, this task can be used to ensure that files to be linked exist before running the check:linked_files task: -{% highlight ruby %} +```ruby namespace :deploy do namespace :check do task :linked_files => 'config/newrelic.yml' @@ -20,4 +20,4 @@ remote_file 'config/newrelic.yml' => '/tmp/newrelic.yml', roles: :app file '/tmp/newrelic.yml' do |t| sh "curl -o #{t.name} https://rpm.newrelic.com/accounts/xx/newrelic.yml" end -{% endhighlight %} +``` diff --git a/documentation/advanced-features/role-filtering/index.markdown b/documentation/advanced-features/role-filtering/index.markdown index 90052c1e..3bf5d118 100644 --- a/documentation/advanced-features/role-filtering/index.markdown +++ b/documentation/advanced-features/role-filtering/index.markdown @@ -27,9 +27,9 @@ There are three ways to specify the role filter. Capistrano will read the role filter from the environment variable `ROLES` if it is set. You can set it inline: -{% highlight bash %} +```bash ROLES=app,web cap production deploy -{% endhighlight %} +``` Specify multiple roles by separating them with a comma. @@ -38,9 +38,9 @@ Specify multiple roles by separating them with a comma. You can set the role filter inside your deploy configuration. For example, you can set the following inside `config/deploy.rb`: -{% highlight ruby %} +```ruby set :filter, :roles => %w{app web} -{% endhighlight %} +``` Note that you specify the filter as an array rather than as a comma-separated list of roles when using this method. @@ -50,9 +50,9 @@ list of roles when using this method. In a similar way to using the environment variable, you can set the role filter by specifying it as a command line argument to `cap`: -{% highlight bash %} +```bash cap --roles=app,web production deploy -{% endhighlight %} +``` Like the environment variable method, specify multiple roles by separating them with a comma. diff --git a/documentation/advanced-features/ssh-kit/index.markdown b/documentation/advanced-features/ssh-kit/index.markdown index 8a454695..2dfc5a19 100644 --- a/documentation/advanced-features/ssh-kit/index.markdown +++ b/documentation/advanced-features/ssh-kit/index.markdown @@ -7,7 +7,7 @@ Capistrano executes commands on remote servers using [**SSHKit**](https://github An example setting a working directory, user and environment variable: -{% highlight ruby %} +```ruby on roles(:app), in: :sequence, wait: 5 do within "/opt/sites/example.com" do # commands in this block execute in the @@ -23,7 +23,7 @@ on roles(:app), in: :sequence, wait: 5 do end end end -{% endhighlight %} +``` For more examples, see the EXAMPLES.md file in the [**SSHKit**](https://github.com/capistrano/sshkit) project: diff --git a/documentation/faq/how-can-i-access-stage-configuration-variables/index.markdown b/documentation/faq/how-can-i-access-stage-configuration-variables/index.markdown index d71d0f3b..62241d95 100644 --- a/documentation/faq/how-can-i-access-stage-configuration-variables/index.markdown +++ b/documentation/faq/how-can-i-access-stage-configuration-variables/index.markdown @@ -4,9 +4,9 @@ layout: default --- Configuration variables are access with the fetch method, like so: -{% highlight ruby %} +```ruby local = fetch(:configuration_variable, _default_value_) -{% endhighlight %} +``` This works fine when accessing configuration variables defined within the same file. For example accessing a previously set configuration variable defined in deploy.rb or accessing a set configuration variable in a stage file. @@ -15,27 +15,27 @@ The deploy.rb configuration is executed first and then the stage file(s) from co For example, let's create a configuration variable in the production and staging files and access the current one from deploy.rb. config/deploy/production.rb -{% highlight ruby %} +```ruby set :app_domain, "www.my_application.com" -{% endhighlight %} +``` config/deploy/staging.rb -{% highlight ruby %} +```ruby set :app_domain, "stage.application_test.com" -{% endhighlight %} +``` These variables are not available in deploy.rb using `fetch(:nginx_port)` or `fetch(:app_domain)` because they are not defined when deploy.rb is executed. They can, however, be lazily loaded using a lambda in deploy.rb like this: config/deploy.rb -{% highlight ruby %} +```ruby set :nginx_server_name, ->{ fetch(:app_domain) } set :puma_bind, ->{ "unix:/tmp/#{fetch(:app_domain)}.sock" } -{% endhighlight %} +``` Now the `:nginx_server_name` and `:puma_bind` variables will be lazily assigned the values set in which ever stage file was used to deploy. If you need to create nested hashes, you might find `do/end` syntax more readable: -{% highlight ruby %} +```ruby set :database_yml, -> do { production: { @@ -43,4 +43,4 @@ set :database_yml, -> do } } end -{% endhighlight %} +``` diff --git a/documentation/faq/how-can-i-check-for-existing-remote-file/index.markdown b/documentation/faq/how-can-i-check-for-existing-remote-file/index.markdown index 513a3020..bdb62c94 100644 --- a/documentation/faq/how-can-i-check-for-existing-remote-file/index.markdown +++ b/documentation/faq/how-can-i-check-for-existing-remote-file/index.markdown @@ -5,9 +5,9 @@ layout: default The `test` method is best used for file checking with bash conditionals -{% highlight ruby %} +```ruby if test("[ -f /tmp/foo ]") # do stuff end -{% endhighlight %} +``` diff --git a/documentation/faq/how-can-i-get-capistrano-to-prompt-for-a-password/index.markdown b/documentation/faq/how-can-i-get-capistrano-to-prompt-for-a-password/index.markdown index 780c3632..3c0bf0fd 100644 --- a/documentation/faq/how-can-i-get-capistrano-to-prompt-for-a-password/index.markdown +++ b/documentation/faq/how-can-i-get-capistrano-to-prompt-for-a-password/index.markdown @@ -5,8 +5,8 @@ layout: default Password authentication can be done via `ask` in your deploy environment file (e.g.: config/environments/production.rb) -{% highlight ruby %} +```ruby # Capistrano > 3.2.0 supports echo: false ask(:password, nil, echo: false) server 'server.domain.com', user: 'ssh_user_name', port: 22, password: fetch(:password), roles: %w{web app db} -{% endhighlight %} +``` diff --git a/documentation/faq/why-does-something-work-in-my-ssh-session-but-not-in-capistrano/index.markdown b/documentation/faq/why-does-something-work-in-my-ssh-session-but-not-in-capistrano/index.markdown index c57a62b6..ae4631ee 100644 --- a/documentation/faq/why-does-something-work-in-my-ssh-session-but-not-in-capistrano/index.markdown +++ b/documentation/faq/why-does-something-work-in-my-ssh-session-but-not-in-capistrano/index.markdown @@ -60,23 +60,23 @@ figure this out! First, we'll try a *real* SSH session, logging in via our terminal, and seeing what happens: -{% highlight bash %} +```bash me@localhost $ ssh me@remote me@remote $ [[ $- == *i* ]] && echo 'Interactive' || echo 'Not interactive' Interactive me@remote $ shopt -q login_shell && echo 'Login shell' || echo 'Not login shell' Login shell -{% endhighlight %} +``` Contrast that with what happens when we hand the command to run to the SSH command line without logging in first... -{% highlight bash %} +```bash me@localhost $ ssh me@remote "[[ $- == *i* ]] && echo 'Interactive' || echo 'Not interactive'" Interactive me@localhost $ ssh me@remote "shopt -q login_shell && echo 'Login shell' || echo 'Not login shell'" Not login shell -{% endhighlight %} +``` Here we can see that Bash is still starting in **interactive** mode when we're just running a single command, that's because the terminal we are using is @@ -86,7 +86,7 @@ When we try the same with Capistrano we'll see yet another set of results; we can have a very simple, Capfile, we don't even need to load the default recipes to test this: -{% highlight ruby %} +```ruby # Capistrano 3 task :query_interactive do on 'me@remote' do @@ -98,16 +98,16 @@ task :query_login do info capture("shopt -q login_shell && echo 'Login shell' || echo 'Not login shell'") end end -{% endhighlight %} +``` Gives us the following: -{% highlight bash %} +```bash me@localhost $ cap query_login INFO Not login shell me@localhost $ cap query_interactive INFO Not interactive -{% endhighlight %} +``` ## Which shell startup files do get loaded? diff --git a/documentation/getting-started/authentication-and-authorisation/index.markdown b/documentation/getting-started/authentication-and-authorisation/index.markdown index e50ff081..2dd5fa29 100644 --- a/documentation/getting-started/authentication-and-authorisation/index.markdown +++ b/documentation/getting-started/authentication-and-authorisation/index.markdown @@ -13,10 +13,10 @@ members) To create this deploy user we'll assume something like the following has been done: -{% highlight bash %} +```bash root@remote $ adduser deploy root@remote $ passwd -l deploy -{% endhighlight %} +``` The first line creates a completely standard user, it has a home directory, which we'll need in a moment, and has a shell, so it may log in. This needs to @@ -54,9 +54,9 @@ public key to the `deploy` user's `authorized_keys` file, that way if someone quits or gets fired, you can remove their key from that file, and the rest of you can keep on shipping! -{% highlight bash %} +```bash me@localhost $ ssh-keygen -t rsa -C 'me@my_email_address.com' -{% endhighlight %} +``` You'll be prompted for a passphrase, that's fine. Type one and keep it safe. This passphrase ensures that if your computer is stolen, people still need a @@ -72,17 +72,17 @@ minutes upwards.) We can see which keys are loaded in the SSH agent by running `ssh-add -l` -{% highlight bash %} +```bash me@localhost $ ssh-add -l 2048 af:ce:7e:c5:93:18:39:ff:54:20:7a:2d:ec:05:7c:a5 /Users/me/.ssh/id_rsa (RSA) -{% endhighlight %} +``` If you don't see any keys listed, you can simply run `ssh-add`: -{% highlight bash %} +```bash me@localhost $ ssh-add Identity added: /Users/me/.ssh/id_rsa (/Users/me/.ssh/id_rsa) -{% endhighlight %} +``` Typically, ssh-add will ask you for the passphrase when you add a key. @@ -98,10 +98,10 @@ At this point with the key loaded into the agent, we need to put the `/home/users/deploy/.ssh/authorized_keys`, to get the contents of that file, we can ask our local key agent for the public parts of the keys it has loaded: -{% highlight bash %} +```bash me@localhost $ ssh-add -L ssh-rsa jccXJ/JRfGxnkh/8iL........dbfCH/9cDiKa0Dw8XGAo01mU/w== /Users/me/.ssh/id_rsa -{% endhighlight %} +``` This will be a lot longer when you run it, I snipped the output because it looked bad. @@ -116,7 +116,7 @@ If you are on linux there often exists a command [`ssh-copy-id`](http://linux.die.net/man/1/ssh-copy-id) which streamlines this process, otherwise the workflow is something like: -{% highlight bash %} +```bash me@localhost $ ssh root@remote root@remote $ su - deploy deploy@remote $ cd ~ @@ -124,7 +124,7 @@ deploy@remote $ mkdir .ssh deploy@remote $ echo "ssh-rsa jccXJ/JRfGxnkh/8iL........dbfCH/9cDiKa0Dw8XGAo01mU/w== /Users/me/.ssh/id_rsa" >> .ssh/authorized_keys deploy@remote $ chmod 700 .ssh deploy@remote $ chmod 600 .ssh/authorized_keys -{% endhighlight %} +``` **Remember:** This needs to be done on every server you want to use, you can use the same key for each one, but only one key per developer is recommended. @@ -132,11 +132,11 @@ use the same key for each one, but only one key per developer is recommended. If we did all that correctly, we should now be able to do something like this: -{% highlight bash %} +```bash me@localhost $ ssh deploy@one-of-my-servers.com 'hostname; uptime' one-of-my-servers.com 19:23:32 up 62 days, 44 min, 1 user, load average: 0.00, 0.01, 0.05 -{% endhighlight %} +``` That should happen without having to enter a passphrase for your SSH key, or prompting you for an SSH password (which the deploy user doesn't have anyway). @@ -164,7 +164,7 @@ charset="utf-8"> If your server isn't accessible directly and you need to use the SSH ProxyCommand option, you should do -{% highlight ruby %} +```ruby require 'net/ssh/proxy/command' set :ssh_options, proxy: Net::SSH::Proxy::Command.new('ssh mygateway.com -W %h:%p') @@ -175,7 +175,7 @@ server 'internal-hostname', ssh_options: { proxy: Net::SSH::Proxy::Command.new('ssh mygateway.com -W %h:%p'), } -{% endhighlight %} +``` #### 1.2 From our servers to the repository host @@ -192,10 +192,10 @@ Github. Here's how we can check if that works, first get the URL of the repository: -{% highlight bash %} +```bash me@localhost $ git config remote.origin.url git@github.com:capistrano/rails3-bootstrap-devise-cancan.git -{% endhighlight %} +``` Here we're listing our private (for testing purposes) fork of the rails3-bootstrap-devise-cancan repository forked from the Rails Examples and @@ -203,13 +203,13 @@ Tutorials project. We can try to access the repository via our server by doing the following: -{% highlight bash %} +```bash # List SSH keys that are loaded into the agent me@localhost $ ssh-add -l # Make sure they key is loaded if 'ssh-add -l' didn't show anything me@localhost $ ssh-add me@localhost $ ssh -A deploy@one-of-my-servers.com 'git ls-remote git@github.com:capistrano/rails3-bootstrap-devise-cancan.git -{% endhighlight %} +``` We first check that the agent has the keys loaded. If not we simply load it and enter the passphrase when prompted. @@ -225,7 +225,7 @@ to the list of known hosts. From the SSH documentation: -{% highlight bash %} +```bash -A Enables forwarding of the authentication agent connection. This can also be specified on a per-host basis in a configuration file. @@ -235,7 +235,7 @@ From the SSH documentation: attacker cannot obtain key material from the agent, however they can perform operations on the keys that enable them to authenticate using the identities loaded into the agent. -{% endhighlight %} +``` In layman's terms, you shouldn't use SSH agent forwarding to machines where you don't trust the administrators, as they can can override the permissions on @@ -254,11 +254,11 @@ Github, we'll be prompted for a username and password: ##### 1.2.2.1 With a regular username/password -{% highlight bash %} +```bash me@localhost $ git ls-remote https://github.com/capistrano/rails3-bootstrap-devise-cancan.git Username for 'https://github.com': myownusername Password for 'https://capistrano@github.com': -{% endhighlight %} +``` This challenge response prompt doesn't work well for automating things, so there are two ways to get around this depending on your server's host @@ -269,11 +269,11 @@ The other mechanism, and the reason that its **very** important to always use HTTPS not plain ol' HTTP is to embed the username and password in the URL, note this won't work well if your password has special characters: -{% highlight bash %} +```bash me@localhost $ git ls-remote https://capistrano:ourverysecretpassword@github.com/capistrano/rails3-bootstrap-devise-cancan.git 3419812c9f146d9a84b44bcc2c3caef94da54758HEAD 3419812c9f146d9a84b44bcc2c3caef94da54758HEADrefs/heads/master -{% endhighlight %} +``` The bigger problem with passwords, whether inlined into the URL, or entered into a `netrc` file, is that the password gives access to **your entire Github @@ -286,11 +286,11 @@ at Github, they recently rolled out a feature called [Personal API Tokens](https://github.com/blog/1509-personal-api-tokens) which allow you to do something like this: -{% highlight bash %} +```bash me@localhost $ git ls-remote https://XXXX:@github.com/capistrano/rails3-bootstrap-devise-cancan.git 3419812c9f146d9a84b44bcc2c3caef94da54758HEAD 3419812c9f146d9a84b44bcc2c3caef94da54758HEADrefs/heads/master -{% endhighlight %} +``` Where `XXXX` is a personal API token, as such: @@ -321,9 +321,9 @@ have configured *passwordless* `sudo`. Configuring `sudo` to give some users access to some commands under some circumstances is beyond the scope of this documentation, but sufficed to say something like: -{% highlight bash %} +```bash deploy ALL=NOPASSWD:/etc/init.d/mysqld, /etc/init.d/apache2 -{% endhighlight %} +``` This example would give the user named `deploy` access to call `sudo /etc/init.d/mysql _________` and the same for the `apache2` control script. @@ -338,7 +338,7 @@ notice a change. To configure this hierarchy, ignoring for the moment the passwordless `sudo` access that you may or may not need depending how well your servers are setup: -{% highlight bash %} +```bash me@localhost $ ssh root@remote # Capistrano will use /var/www/....... where ... is the value set in # :application, you can override this by setting the ':deploy_to' variable @@ -349,7 +349,7 @@ root@remote $ umask 0002 root@remote $ chmod g+s ${deploy_to} root@remote $ mkdir ${deploy_to}/{releases,shared} root@remote $ chown deploy ${deploy_to}/{releases,shared} -{% endhighlight %} +``` **Note:** The `chmod g+s` is a really handy, and little known Unix feature, it means that at the operating system level, without having to pay much attention @@ -362,12 +362,12 @@ group: read/write, other: none*. This means that we'll be able to read these files from Apache, or our web server by running the web server in the `deploy` group namespace. -{% highlight bash %} +```bash root@remote # stat -c "%A (%a) %n" ${deploy_to}/ drwx--S--- (2700) /var/www/rails3-bootstrap-devise-cancan-demo root@remote # stat -c "%A (%a) %n" ${deploy_to}/* drwxrwsr-x (2775) /var/www/rails3-bootstrap-devise-cancan-demo/releases drwxrwsr-x (2775) /var/www/rails3-bootstrap-devise-cancan-demo/shared -{% endhighlight %} +``` diff --git a/documentation/getting-started/before-after/index.markdown b/documentation/getting-started/before-after/index.markdown index fab212fb..f07171e5 100644 --- a/documentation/getting-started/before-after/index.markdown +++ b/documentation/getting-started/before-after/index.markdown @@ -5,7 +5,7 @@ layout: default Where calling on the same task name, executed in order of inclusion -{% highlight ruby %} +```ruby # call an existing task before :starting, :ensure_user @@ -20,12 +20,12 @@ end after :finishing, :notify do # end -{% endhighlight %} +``` If it makes sense for your use case (often, that means *generating a file*) the Rake prerequisite mechanism can be used: -{% highlight ruby %} +```ruby desc "Create Important File" file 'important.txt' do |t| sh "touch #{t.name}" @@ -36,11 +36,11 @@ task :upload => 'important.txt' do |t| upload!(t.prerequisites.first, '/tmp') end end -{% endhighlight %} +``` The final way to call out to other tasks is to simply `invoke()` them: -{% highlight ruby %} +```ruby namespace :example do task :one do on roles(:all) { info "One" } @@ -50,6 +50,6 @@ namespace :example do on roles(:all) { info "Two" } end end -{% endhighlight %} +``` This method is widely used. diff --git a/documentation/getting-started/cold-start/index.markdown b/documentation/getting-started/cold-start/index.markdown index 8f14f7b0..5d5e3c74 100644 --- a/documentation/getting-started/cold-start/index.markdown +++ b/documentation/getting-started/cold-start/index.markdown @@ -20,7 +20,7 @@ technologies. ### 1. Checking the directory structure on the remote machine: -{% highlight bash %} +```bash me@localhost $ ssh deploy@remote 'ls -lR /var/www/my-application' my-application: total 8 @@ -32,7 +32,7 @@ total 0 my-application/shared: total 0 -{% endhighlight %} +``` This checks in one simple command that the ssh keys you setup are working (you might yet be prompted for the password), and the permissions on the directory @@ -44,7 +44,7 @@ Now that we know how to check for permissions, and repository access, we'll quickly introduce ourselves to a quick Cap task to check these things on all the machines for us: -{% highlight ruby %} +```ruby desc "Check that we can access everything" task :check_write_permissions do on roles(:all) do |host| @@ -55,7 +55,7 @@ task :check_write_permissions do end end end -{% endhighlight %} +``` Running this should give you a pretty decent overview, one line of output for each server. It's also your first introduction to the API of Capistrano for @@ -70,22 +70,22 @@ later, but add those lines to a file in `./lib/capistrano/tasks`, call it something like `access_check.rake`, and run `cap -T` from the top directory and we'll be able to see the task listed: -{% highlight bash %} +```bash me@localhost $ bundle exec cap -T # ... lots of other tasks ... cap check_write_permissions # Check that we can access everything # ... lots of other tasks ... -{% endhighlight %} +``` Then we simply call it: -{% highlight bash %} +```bash me@localhost $ bundle exec cap staging check_write_permissions DEBUG [82c92144] Running /usr/bin/env [ -w /var/www/my-application ] on myserver.com DEBUG [82c92144] Command: [ -w /var/www/my-application ] DEBUG [82c92144] Finished in 0.456 seconds command successful. INFO /var/www/my-application is writable on myserver.com -{% endhighlight %} +``` If we've done something wrong, that won't happen and we'll know that we need to jump on the mailing list to get help, into IRC or ask a friend. @@ -98,9 +98,9 @@ wrap Git in a shell script that makes it behave. Capistrano does just this, so to check if the Git access is working, we can simply call: -{% highlight bash %} +```bash me@localhost $ cap staging git:check -{% endhighlight %} +``` This task is defined in the default Git SCM-strategy and looks a lot like what we wrote above to check the file permissions, however the Git check recipe is @@ -111,7 +111,7 @@ for us by Capistrano. (This is one of the pieces we inherit from Rake) If this fails we'll see: -{% highlight bash %} +```bash me@localhost $ cap staging git:check cap staging git:check DEBUG Uploading /tmp/git-ssh.sh 0% @@ -130,7 +130,7 @@ git stderr: Nothing written Tasks: TOP => git:check (See full trace by running task with --trace) -{% endhighlight %} +``` This'll typically come out looking more beautiful depending on your terminal colour support, you may well see something like this: @@ -155,7 +155,7 @@ In this case, we'll be using SSH agent forwarding, we can check if that's working by writing a tiny Cap task, or simply using SSH to do it for us, the choice is yours: -{% highlight ruby %} +```ruby # lib/capistrano/tasks/agent_forwarding.rake desc "Check if agent forwarding is working" task :forwarding do @@ -167,32 +167,32 @@ task :forwarding do end end end -{% endhighlight %} +``` That gave the output: -{% highlight bash %} +```bash cap staging forwarding DEBUG [f1269276] Running /usr/bin/env env | grep SSH_AUTH_SOCK on example.com DEBUG [f1269276] Command: env | grep SSH_AUTH_SOCK DEBUG [f1269276] SSH_AUTH_SOCK=/tmp/ssh-nQUEmyQ2nS/agent.2546 DEBUG [f1269276] Finished in 0.453 seconds command successful. INFO Agent forwarding is up to example.com -{% endhighlight %} +``` If you don't feel like writing a Capistrano task, one could simply do: -{% highlight bash %} +```bash me@localhost $ ssh -A example.com 'env | grep SSH_AUTH_SOCK' SSH_AUTH_SOCK=/tmp/ssh-Tb6X8V53tm/agent.2934 -{% endhighlight %} +``` If we see the `SSH_AUTH_SOCK` output, that's a pretty good indication that SSH agent forwarding is enabled, and if on your local machine `ssh-add -l` shows you an SSH key, then we're good to go. **Make sure that you're using the `git@...` repository URL** -{% highlight bash %} +```bash cap staging git:check DEBUG Uploading /tmp/git-ssh.sh 0% INFO Uploading /tmp/git-ssh.sh 100% @@ -204,6 +204,6 @@ DEBUG [f40edfbb] Command: ( GIT_ASKPASS=/bin/echo GIT_SSH=/tmp/git-ssh.sh /usr/b DEBUG [f40edfbb] 3419812c9f146d9a84b44bcc2c3caef94da54758 HEAD DEBUG [f40edfbb] 3419812c9f146d9a84b44bcc2c3caef94da54758 refs/heads/master INFO [f40edfbb] Finished in 3.319 seconds command successful. -{% endhighlight %} +``` ![Capistrano Git Check Colour Example](/images/successful-git-check-example-screenshot.png) diff --git a/documentation/getting-started/configuration/index.markdown b/documentation/getting-started/configuration/index.markdown index 8ed394a6..0ddf26f0 100644 --- a/documentation/getting-started/configuration/index.markdown +++ b/documentation/getting-started/configuration/index.markdown @@ -16,23 +16,23 @@ Configuration variables can be either global or specific to your stage. Each variable can be set to a specific value: -{% highlight ruby %} +```ruby set :application, 'MyLittleApplication' # use a lambda to delay evaluation set :application, -> { "SomeThing_#{fetch :other_config}" } -{% endhighlight %} +``` A value can be retrieved from the configuration at any time: -{% highlight ruby %} +```ruby fetch :application # => "MyLittleApplication" fetch(:special_thing, 'some_default_value') # will return the value if set, or the second argument as default value -{% endhighlight %} +``` ## Variables diff --git a/documentation/getting-started/flow/index.markdown b/documentation/getting-started/flow/index.markdown index 3fa72a61..bc1e2dfe 100644 --- a/documentation/getting-started/flow/index.markdown +++ b/documentation/getting-started/flow/index.markdown @@ -10,7 +10,7 @@ Capistrano v3 provides a default **deploy flow** and a **rollback flow**: When you run `cap production deploy`, it invokes the following tasks in sequence: -{% highlight ruby %} +```ruby deploy:starting - start a deployment, make sure everything is ready deploy:started - started hook (for custom tasks) deploy:updating - update server(s) with a new release @@ -19,7 +19,7 @@ deploy:publishing - publish the new release deploy:published - published hook deploy:finishing - finish the deployment, clean up everything deploy:finished - finished hook -{% endhighlight %} +``` Notice there are several hook tasks e.g. `:started`, `:updated` for you to hook up custom tasks into the flow using `after()` and `before()`. @@ -29,7 +29,7 @@ you to hook up custom tasks into the flow using `after()` and `before()`. When you run `cap production deploy:rollback`, it invokes the following tasks in sequence: -{% highlight ruby %} +```ruby deploy:starting deploy:started deploy:reverting - revert server(s) to previous release @@ -38,7 +38,7 @@ deploy:publishing deploy:published deploy:finishing_rollback - finish the rollback, clean up everything deploy:finished -{% endhighlight %} +``` As you can see, rollback flow shares many tasks with deploy flow. But note that, rollback flow runs its own `:finishing_rollback` task because its @@ -48,18 +48,18 @@ cleanup process is usually different from deploy flow. Assume you require the following files in `Capfile`, -{% highlight ruby %} +```ruby # Capfile require 'capistrano/setup' require 'capistrano/deploy' require 'capistrano/bundler' require 'capistrano/rails/migrations' require 'capistrano/rails/assets' -{% endhighlight %} +``` When you run `cap production deploy`, it runs these tasks: -{% highlight ruby %} +```ruby deploy deploy:starting [before] @@ -84,11 +84,11 @@ deploy deploy:cleanup deploy:finished deploy:log_revision -{% endhighlight %} +``` For `cap production deploy:rollback`, it runs these tasks: -{% highlight ruby %} +```ruby deploy deploy:starting [before] @@ -108,4 +108,4 @@ deploy deploy:cleanup_rollback deploy:finished deploy:log_revision -{% endhighlight %} +``` diff --git a/documentation/getting-started/installation/index.markdown b/documentation/getting-started/installation/index.markdown index c58d5103..4e8387a0 100644 --- a/documentation/getting-started/installation/index.markdown +++ b/documentation/getting-started/installation/index.markdown @@ -17,28 +17,28 @@ therefore recommended to use an appropriate bundler. The following command will install the latest released capistrano `v3` revision: -{% highlight bash %} +```bash $ gem install capistrano -{% endhighlight %} +``` Or grab the bleeding edge head from: -{% highlight bash %} +```bash $ git clone https://github.com/capistrano/capistrano.git $ cd capistrano $ gem build *.gemspec $ gem install *.gem -{% endhighlight %} +``` ### Usage in a Rails project Add the following lines to the Gemfile: -{% highlight ruby %} +```ruby group :development do gem 'capistrano-rails', '~> 1.1.1' end -{% endhighlight %} +``` The `capistrano-rails` gem includes extras specifically designed for Ruby on Rails, specifically: @@ -53,9 +53,9 @@ The documentation for these components can be found in part, to get the best, and most sensible results, simply `require` in Capfile, after the `require 'capistrano/deploy'` line: -{% highlight ruby %} +```ruby require 'capistrano/rails' -{% endhighlight %} +``` ##### Help! I was using Capistrano `v2.x` and I didn't want to upgrade! @@ -64,9 +64,9 @@ If you are using Capistrano `v2.x.x` and have also installed Capistrano `v3` by mistake, then you can lock your Gem version for Capistrano at something like: -{% highlight ruby %} +```ruby gem 'capistrano', '~> 2.15' # Or whatever patch release you are using -{% endhighlight %} +``` This is the [pessimistic operator][rubygems-pessimistic-operator] which installs the closest matching version, at the time of writing this would diff --git a/documentation/getting-started/local-tasks/index.markdown b/documentation/getting-started/local-tasks/index.markdown index 3d0faa57..c21c680d 100644 --- a/documentation/getting-started/local-tasks/index.markdown +++ b/documentation/getting-started/local-tasks/index.markdown @@ -5,7 +5,7 @@ layout: default Local tasks can be run by replacing `on` with `run_locally`: -{% highlight ruby %} +```ruby desc 'Notify service of deployment' task :notify do run_locally do @@ -14,22 +14,22 @@ task :notify do end end end -{% endhighlight %} +``` Of course, you can always just use standard ruby syntax to run things locally: -{% highlight ruby %} +```ruby desc 'Notify service of deployment' task :notify do %x('RAILS_ENV=development bundle exec rake "service:notify"') end -{% endhighlight %} +``` Alternatively you could use the rake syntax: -{% highlight ruby %} +```ruby desc "Notify service of deployment" task :notify do sh 'RAILS_ENV=development bundle exec rake "service:notify"' end -{% endhighlight %} +``` diff --git a/documentation/getting-started/structure/index.markdown b/documentation/getting-started/structure/index.markdown index 122e2248..866655c0 100644 --- a/documentation/getting-started/structure/index.markdown +++ b/documentation/getting-started/structure/index.markdown @@ -7,14 +7,14 @@ Capistrano uses a strictly defined directory hierarchy on each remote server to Assuming your `config/deploy.rb` contains this: -{% highlight ruby %} +```ruby set :deploy_to, '/var/www/my_app_name' -{% endhighlight %} +``` Then inspecting the directories inside `/var/www/my_app_name` looks like this: -{% highlight bash %} +```bash ├── current -> /var/www/my_app_name/releases/20150120114500/ ├── releases │   ├── 20150080072500 @@ -27,7 +27,7 @@ Then inspecting the directories inside `/var/www/my_app_name` looks like this: ├── revisions.log └── shared └── -{% endhighlight %} +``` * `current` is a symlink pointing to the latest release. This symlink is diff --git a/documentation/getting-started/tasks/index.markdown b/documentation/getting-started/tasks/index.markdown index e7f0c63d..5a4911e5 100644 --- a/documentation/getting-started/tasks/index.markdown +++ b/documentation/getting-started/tasks/index.markdown @@ -3,7 +3,7 @@ title: Tasks layout: default --- -{% highlight ruby %} +```ruby server 'example.com', roles: [:web, :app] server 'example.org', roles: [:db, :workers] desc "Report Uptimes" @@ -13,7 +13,7 @@ task :uptime do info "Host #{host} (#{host.roles.to_a.join(', ')}):\t#{capture(:uptime)}" end end -{% endhighlight %} +``` **Note**: diff --git a/documentation/getting-started/user-input/index.markdown b/documentation/getting-started/user-input/index.markdown index b2be70e3..aa35323a 100644 --- a/documentation/getting-started/user-input/index.markdown +++ b/documentation/getting-started/user-input/index.markdown @@ -5,7 +5,7 @@ layout: default User input can be required in a task or during configuration: -{% highlight ruby %} +```ruby # used in a configuration set :database_name, ask('Enter the database name:') @@ -17,32 +17,32 @@ task :breakfast do execute "echo \"$(whoami) wants #{fetch(:breakfast)} for breakfast!\"" end end -{% endhighlight %} +``` When using `ask` to get user input, you can pass `echo: false` to prevent the input from being displayed. This option should be used to ask the user for passwords and other sensitive data during a deploy run. -{% highlight ruby %} +```ruby set :database_password, ask('Enter the database password:', 'default', echo: false) -{% endhighlight %} +``` If you only pass in a symbol this will be printed as text for the user and the input will be saved to this variable: -{% highlight ruby %} +```ruby ask(:database_encoding, 'UTF-8') fetch(:database_encoding) # => contains the user input (or the default) # once the above line got executed -{% endhighlight %} +``` You can use `ask` to set a server- or role-specific configuration variable. -{% highlight ruby %} +```ruby set :password, ask('Server password', nil) server 'example.com', user: 'ssh_user_name', port: 22, password: fetch(:password), roles: %w{web app db} -{% endhighlight %} +``` diff --git a/documentation/overview/what-is-capistrano/index.markdown b/documentation/overview/what-is-capistrano/index.markdown index 5afa2c20..b7f832d6 100644 --- a/documentation/overview/what-is-capistrano/index.markdown +++ b/documentation/overview/what-is-capistrano/index.markdown @@ -22,9 +22,9 @@ Ruby software to form part of a larger tool. #### What does it look like? -{% highlight bash %} +```bash me@localhost $ cap staging deploy -{% endhighlight %} +```
DEBUG Uploading /tmp/git-ssh.sh 0%
@@ -98,7 +98,7 @@ There's lots of cool stuff in the Capistrano toy box:
 * Support for complex environments.
 * A sane, expressive API:
 
-{% highlight ruby %}
+```ruby
 desc "Show off the API"
 task :ditty do
 
@@ -143,4 +143,4 @@ task :ditty do
     end
   end
 end
-{% endhighlight %}
+```
diff --git a/documentation/upgrading/index.markdown b/documentation/upgrading/index.markdown
index 6f4f44ce..8d2d0596 100644
--- a/documentation/upgrading/index.markdown
+++ b/documentation/upgrading/index.markdown
@@ -8,37 +8,37 @@ Update your Gemfile: `gem 'capistrano', '~> 3.0', require: false, group: :develo
 
 
 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 %}
+```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 %}
+```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.
 
-{% highlight bash %}
+```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:
 
-{% highlight bash %}
+```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.
@@ -50,11 +50,11 @@ Update `config/deploy/production.rb` and `config/deploy/staging.rb` to have rele
 5.
 If you had a gateway server set doing `set :gateway, "www.capify.org"` you should upgrade to
 
-{% highlight ruby %}
+```ruby
 require 'net/ssh/proxy/command'
 
 set :ssh_options, proxy: Net::SSH::Proxy::Command.new('ssh mygateway.com -W %h:%p')
-{% endhighlight %}
+```
 
 Or the per-server `ssh_options` equivalent.
 
@@ -68,19 +68,19 @@ Notice that some parameters are not necessary anymore: `use_sudo`, `normalize_as
 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:
 
-{% highlight ruby %}
+```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.
 
 8.
 Keep editing Capfile and uncomment addons you need, such as rbenv/rvm, bundler or rails.
-{% highlight ruby %}
+```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.
@@ -91,16 +91,16 @@ Yay! Try to deploy with your new config set. If you discover any missing info in
 
 Instead of:
 
-{% highlight ruby %}
+```ruby
 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 %}
+```ruby
 on roles :all do
   within fetch(:latest_release_directory) do
     with rails_env: fetch(:rails_env) do
@@ -108,13 +108,13 @@ on roles :all do
     end
   end
 end
-{% endhighlight %}
+```
 
 Note: 'within' blocks are required to be wrapped in an 'on' block for the dsl to recognize it
 
 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 %}
+```ruby
 on roles :all do
   within fetch(:latest_release_directory) do
     with rails_env: fetch(:rails_env), rails_relative_url_root: '/home' do
@@ -122,4 +122,4 @@ on roles :all do
     end
   end
 end
-{% endhighlight %}
+```
diff --git a/index.markdown b/index.markdown
index 91b75031..2241ed63 100644
--- a/index.markdown
+++ b/index.markdown
@@ -5,7 +5,7 @@ title: A remote server automation and deployment tool written in Ruby.
 
 ### A Simple Task
 
-{% highlight ruby %}
+```ruby
 role :demo, %w{example.com example.org example.net}
 task :uptime do
   on roles(:demo), in: :parallel do |host|
@@ -13,7 +13,7 @@ task :uptime do
     puts "#{host.hostname} reports: #{uptime}"
   end
 end
-{% endhighlight %}
+```
 
 Capistrano extends the *Rake* DSL with methods specific to running commands
 `on()` servers.