ASDF support for Capistrano v3:

If you use this integration with capistrano-rails, please ensure that you have capistrano-bundler >= 1.1.0.

Add this line to your application's Gemfile:

# Gemfile
gem 'capistrano', '~> 3.0'
gem 'capistrano-asdf'

And then execute:

$ bundle install

Require in Capfile to use the default task:

# Capfile
require 'capistrano/asdf'

And you should be good to go!

Everything should work for a basic ASDF setup out of the box. However we strongly encourage you to use the .tool-versions for proper tool version selection.

If you need some special settings, set those in the stage file for your server:

# deploy.rb or stage file (staging.rb, production.rb or else)
set :asdf_custom_path, '~/.my_asdf_installation_path'  # only needed if not '~/.asdf'
set :asdf_tools, %w{ ruby }                            # defaults to %{ ruby nodejs }
set :asdf_map_ruby_bins, %w{ bundle gem }              # defaults to %w{ rake gem bundle ruby rails }
set :asdf_map_nodejs_bins, %w{ node npm }              # defaults to %w{ node npm yarn }

If you have a custom ASDF setup with a different path then expected, you have to define a custom ASDF path to tell capistrano where it is.

If you don't want to use all the tools available (ruby and nodejs), you have to define which one you want to use.

For example; if you just want to use ASDF for ruby, you may set :asdf_tools:

set :asdf_tools, %w{ ruby }

If you want to add or remove which ruby related binaries will be mapped to ASDF ruby installation, you have to define which one you want to be mapped.

For example; if you just want to map bundle and gem ruby binaries, you may set :asdf_map_ruby_bins:

set :asdf_map_ruby_bins, %w{ bundle gem }

If you want to add or remove which nodejs related binaries will be mapped to ASDF nodejs installation, you have to define which one you want to be mapped.

For example; if you just want to map node and npm nodejs binaries, you may set :asdf_map_nodejs_bins:

set :asdf_map_nodejs_bins, %w{ node npm }

Capistrano can't use ASDF to install rubies, nodes or other tools yet. So on the servers you are deploying to, you will have to manually use ASDF to install the proper rubies, nodes or other tools.

This gem adds new tasks asdf:map_* before deploy task. It loads the ASDF tools environment for capistrano when it wants to run some tools related programs like rake, gem, bundle, node, npm ...

The ASDF wrapper is needed to correctly run the mapped commands. Since the wrapper is an executable script, it can be used in Systemd units.

$ cap production asdf:upload_wrapper

This task is automaticaly called before asdf:check

If you want your tools (ruby, nodejs) to be installed, you can use the asdf:install task to preform plugins add and then install of required versions from your .tool-versions. asdf:install will automaticaly add necessary plugins running asdf:add_plugins. If you want to change the plugins to install you may set :asdf_tools accordingly.

$ cap production asdf:install

If you want to check your configuration you can use the asdf:check task to get information about the ASDF version and ruby/nodejs tools which would be used for deployment.

$ cap production asdf:check

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request