Capistrano::ASDF
ASDF support for Capistrano v3:
Notes
If you use this integration with capistrano-rails, please ensure that you have capistrano-bundler >= 1.1.0
.
Installation
Add this line to your application's Gemfile:
# Gemfile
gem 'capistrano', '~> 3.0'
gem 'capistrano-asdf'
And then execute:
$ bundle install
Usage
Require in Capfile to use the default task:
# Capfile
require 'capistrano/asdf'
And you should be good to go!
Configuration
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 }
Custom ASDF path: :asdf_custom_path
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.
Custom ASDF tools selection: :asdf_tools
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 }
Custom ASDF ruby binaries selection: :asdf_map_ruby_bins
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 }
Custom ASDF nodejs binaries selection: :asdf_map_nodejs_bins
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 }
Restrictions
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.
How it works
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
...
Generate and upload the ASDF commands wrapper
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
Install required tools
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
Check your configuration
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
Contributing
- Fork it
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create new Pull Request