diff --git a/source/guides/deploying.html.haml b/source/guides/deploying.html.haml
deleted file mode 100644
index 797d32cbbe..0000000000
--- a/source/guides/deploying.html.haml
+++ /dev/null
@@ -1,161 +0,0 @@
----
-title: How to deploy bundled applications
----
-.container.guide
- %h2 How to deploy bundled applications
- .contents
- .bullet
- .description
- Before deploying an app that uses Bundler, Add your Gemfile
- and Gemfile.lock
to source control, but ignore the
- .bundle
folder, which is specific to each machine.
- :code
- $ echo ".bundle" >> .gitignore
- $ git add Gemfile Gemfile.lock .gitignore
- $ git commit -m "Add Bundler support"
- .notes
- Once you have done that, there are two ways to deploy using Bundler:
- manually or automatically.
-
- .bullet
- .description
- %h3 Manual deployment
- In your deploy script, after updating to the latest
- code, install your bundle to the vendor/bundle
- directory, ensuring all your dependencies are met.
- :code
- $ bundle install --deployment
- .notes
- %p
- Start your application servers as usual, and your
- application will use your bundled environment
- with the exact same gems you use in development.
-
- %p
- If you have run bundle package
, the cached
- gems will be used automatically.
-
- = link_to 'Learn More: Packing', '/man/bundle-cache.1.html', class: 'btn btn-primary'
-
- .bullet
- %h3 Automatic deployment with Capistrano
- .description
- To pull in the Bundler Cap task, just add this to your
- deploy.rb
file:
- :code
- # lang: ruby
- require 'bundler/capistrano'
- .notes
- That's it! Running cap deploy
will now automatically run
- bundle install
on the remote server with deployment-friendly
- options. A list of options that can be changed is available in the help
- for the cap task. To see it, run cap -e bundle:install
.
-
- .bullet
- .description
- %h3 Automatic deployment with Vlad
- There is a default Vlad task available. To make it available, add this line
- to the Vlad deploy.rb
.
- :code
- # lang: ruby
- require 'bundler/vlad'
- .notes
- Once you have done that, the vlad:bundle:install
task will be
- available for use. Make sure it is run as part of your deploy. For example:
- :code
- # lang: ruby
- task "vlad:deploy" => %w[
- vlad:update vlad:bundle:install vlad:start_app vlad:cleanup
- ]
-
- .bullet
- .description
- %h3 After deploying
- Make sure to use bundle exec
to run any executables
- from gems in the bundle
- :code
- $ bundle exec rake db:setup
- .notes
- Alternatively, you can use the --binstubs
option on the
- install command to generate executable binaries that can be used instead of
- bundle exec
.
- = link_to 'Learn More: Executables', '/man/bundle-exec.1.html', class: 'btn btn-primary'
-
- .bullet
- .description
- %h3 Heroku
- When you deploy to Heroku, Bundler will be run automatically as long as a Gemfile is present.
- If you check in your Gemfile.lock, Heroku will run `bundle install --deployment`
.
- If you want to exclude certain groups using the --without
option, you need to use `heroku config`
.
- :code
- $ heroku config:set BUNDLE_WITHOUT="test development" --app app_name
- = link_to 'Heroku Bundler Documentation', 'http://docs.heroku.com/bundler', class: 'btn btn-primary'
-
- %h2#deploying-your-application
- Deploying Your Application
-
- .bullet
- .description
- When you run bundle install
, bundler will (by default), install your gems
- to your system repository of gems. This means that they will show up in gem
- list
. Additionally, if you are developing a number of applications, you will not
- need to download and install gems in common for each application. This is nice for
- development, but somewhat problematic for deployment.
-
- %p.description
- In a deployment scenario, the Unix user you deploy with may not have access to install
- gems to a system location. Even if the user does (or you use sudo
), the
- user that boots the application may not have access to them. For instance, Passenger
- runs its Ruby subprocesses with the user nobody
, a somewhat restricted
- user. The tradeoffs in a deployment environment lean more heavily in favor of isolation
- (even at the cost of a somewhat slower deploy-time bundle install
when some
- third-party dependencies have changed).
-
- %p.description
- As a result, bundler comes with a --deployment
flag that encapsulates the
- best practices for using bundler in a deployment environment. These practices are based
- on significant feedback we have received during the development of bundler, as well as a
- number of bug reports that mostly reflected a misunderstanding of how to best configure
- bundler for deployment. The --deployment
flags adds the following defaults:
-
- .description
- %ul
- %li
- Instead of installing gems to the system location, bundler will install gems to
- vendor/bundle
inside your application. Bundler will transparently remember
- this location when you invoke it inside your application (with
- Bundler.setup
and Bundler.require
).
- %li
- Bundler will not use gems already installed to your system, even if they exist.
- %li
- If you have run bundle pack
, checked in the vendor/cache
- directory, and do not have any git gems, Bundler will not contact the internet while
- installing your bundle.
- %li
- Bundler will require a Gemfile.lock
snapshot, and fail if you did not
- provide one.
- %li
- Bundler will not transparently update your Gemfile.lock
if it is out of
- date with your Gemfile
-
- %p.description
- If you use Capistrano, you should symlink vendor/bundle
to
- shared/vendor_bundle
so that bundler will share your installed gems between
- deployments (making things zippy if you didn't make any changes), but still give you the
- benefits of isolation from other applications.
-
- %p.description
- By defaulting the bundle directory to vendor/bundle
, and installing your
- bundle as part of your deployment process, you can be sure that the same Unix user that
- checked out your application also installed the third-party code your application needs.
- This means that if Passenger (or Unicorn) can see your application, it can also see its
- dependencies.
-
- %p.description
- The --deployment
flag requires an up-to-date Gemfile.lock
to
- ensure that the testing you have done (in development and staging) actually reflects the
- code you put into production. You can run bundle check
before deploying
- your application to make sure that your Gemfile.lock
is up-to-date. Note
- that it will always be up-to-date if you have run bundle install
,
- successfully booted your application (or run your tests) since the last time you changed
- your Gemfile
.
diff --git a/source/guides/deploying.html.md b/source/guides/deploying.html.md
new file mode 100644
index 0000000000..57e205b34e
--- /dev/null
+++ b/source/guides/deploying.html.md
@@ -0,0 +1,151 @@
+---
+title: How to deploy bundled applications
+---
+
+## How to deploy bundled applications
+
+Before deploying an app that uses Bundler, Add your `Gemfile`
+and `Gemfile.lock` to source control, but ignore the
+`.bundle` folder, which is specific to each machine.
+
+~~~
+$ echo ".bundle" >> .gitignore
+$ git add Gemfile Gemfile.lock .gitignore
+$ git commit -m "Add Bundler support"
+~~~
+
+Once you have done that, there are two ways to deploy using Bundler:
+manually or automatically.
+
+### Manual deployment
+
+In your deploy script, after updating to the latest
+code, install your bundle to the `vendor/bundle`
+directory, ensuring all your dependencies are met.
+
+~~~
+$ bundle install --deployment
+~~~
+
+Start your application servers as usual, and your
+application will use your bundled environment
+with the exact same gems you use in development.
+
+If you have run `bundle package`, the cached
+gems will be used automatically.
+
+Learn More: Packing
+
+### Automatic deployment with Capistrano
+
+To pull in the Bundler Cap task, just add this to your
+`deploy.rb` file:
+
+~~~ruby
+require 'bundler/capistrano'
+~~~
+
+That's it! Running `cap deploy` will now automatically run
+`bundle install` on the remote server with deployment-friendly
+options. A list of options that can be changed is available in the help
+for the cap task. To see it, run `cap -e bundle:install`.
+
+### Automatic deployment with Vlad
+
+There is a default Vlad task available. To make it available, add this line
+to the Vlad `deploy.rb`.
+
+~~~ruby
+require 'bundler/vlad'
+~~~
+
+Once you have done that, the `vlad:bundle:install` task will be
+available for use. Make sure it is run as part of your deploy. For example:
+
+~~~ruby
+task "vlad:deploy" => %w[
+ vlad:update vlad:bundle:install vlad:start_app vlad:cleanup
+]
+~~~
+
+### After deploying
+
+Make sure to use `bundle exec` to run any executables
+from gems in the bundle
+
+~~~
+$ bundle exec rake db:setup
+~~~
+
+Alternatively, you can use the `--binstubs` option on the
+install command to generate executable binaries that can be used instead of
+`bundle exec`.
+
+Learn More: Executables
+
+### Heroku
+
+When you deploy to Heroku, Bundler will be run automatically as long as a Gemfile is present.
+If you check in your Gemfile.lock, Heroku will run `bundle install --deployment`.
+If you want to exclude certain groups using the `--without` option, you need to use `heroku config`.
+
+~~~
+$ heroku config:set BUNDLE_WITHOUT="test development" --app app_name
+~~~
+
+Heroku Bundler Documentation
+
+## Deploying Your Application
+
+
+When you run `bundle install`, bundler will (by default), install your gems
+to your system repository of gems. This means that they will show up in `gem
+list`. Additionally, if you are developing a number of applications, you will not
+need to download and install gems in common for each application. This is nice for
+development, but somewhat problematic for deployment.
+
+In a deployment scenario, the Unix user you deploy with may not have access to install
+gems to a system location. Even if the user does (or you use `sudo`), the
+user that boots the application may not have access to them. For instance, Passenger
+runs its Ruby subprocesses with the user `nobody`, a somewhat restricted
+user. The tradeoffs in a deployment environment lean more heavily in favor of isolation
+(even at the cost of a somewhat slower deploy-time `bundle install` when some
+third-party dependencies have changed).
+
+As a result, bundler comes with a `--deployment` flag that encapsulates the
+best practices for using bundler in a deployment environment. These practices are based
+on significant feedback we have received during the development of bundler, as well as a
+number of bug reports that mostly reflected a misunderstanding of how to best configure
+bundler for deployment. The `--deployment` flags adds the following defaults:
+
+- Instead of installing gems to the system location, bundler will install gems to
+`vendor/bundle` inside your application. Bundler will transparently remember
+this location when you invoke it inside your application (with
+`Bundler.setup` and `Bundler.require`).
+- Bundler will not use gems already installed to your system, even if they exist.
+- If you have run `bundle pack`, checked in the `vendor/cache`
+directory, and do not have any git gems, Bundler will not contact the internet while
+installing your bundle.
+- Bundler will require a `Gemfile.lock` snapshot, and fail if you did not
+provide one.
+- Bundler will not transparently update your `Gemfile.lock` if it is out of
+date with your `Gemfile`
+
+If you use Capistrano, you should symlink `vendor/bundle` to
+`shared/vendor_bundle` so that bundler will share your installed gems between
+deployments (making things zippy if you didn't make any changes), but still give you the
+benefits of isolation from other applications.
+
+By defaulting the bundle directory to `vendor/bundle`, and installing your
+bundle as part of your deployment process, you can be sure that the same Unix user that
+checked out your application also installed the third-party code your application needs.
+This means that if Passenger (or Unicorn) can see your application, it can also see its
+dependencies.
+
+The `--deployment` flag requires an up-to-date `Gemfile.lock` to
+ensure that the testing you have done (in development and staging) actually reflects the
+code you put into production. You can run `bundle check` before deploying
+your application to make sure that your `Gemfile.lock` is up-to-date. Note
+that it will always be up-to-date if you have run `bundle install`,
+successfully booted your application (or run your tests) since the last time you changed
+your `Gemfile`.