Mina Upgrading notes

Upgrading notes

Upgrading to v0.2.0

Note: these are upgrade notes to the unreleased v0.2.0 version due to be released soon.

Mina v0.2.0 is backwards-compatible, except for the deprecated :revision setting (which wasn’t widely used anyway). However, Mina 0.2.0 adds new features and conveniences that may make it easier to implement tasks you’re already doing.

New default script

The new default deploy script generated by mina init has been improved to add more helpful comments to get you started. While not really necessary, try doing mina init in an empty directory to see the new default script.

# In an empty directory:
$ mina init
$ cat config/deploy.rb

RVM support

The previous recommendation was to make your ~/.bashrc load RVM. This was a little problematic: in Ubuntu systems, RVM wasn’t always loaded because .bashrc wasn’t loaded entirely in interactive shells. Also, some people prefer to load RVM in ~/.bash_profile.

To use RVM on Mina 0.2, make a task called :environment and from there, invoke rvm:use[RUBY_VERSION@GEMSET] like so:

# config/deploy.rb
require 'mina/rvm'

task :enviroment do
  invoke :'rvm:use[ruby-1.9.2@default]'
end

task :deploy => :environment do
  ...
  # continue as usual
  ...
end

You do not need to create an .rvmrc file, although it is supported. In fact, as .rvmrc files are usually environment-specific, this practice is discouraged.

A sample configuration can be seen by creating a new project using mina init (see “New default script” section above).

rbenv support

Mina v0.2 also features rbenv support. Like in RVM, older solutions of loading rbenv in ~/.bashrc will continue to work, however you’re recommended to use the new rbenv:load task.

# config/deploy.rb
require 'mina/rbenv'

task :enviroment do
  invoke :'rbenv:load'
end

task :deploy => :environment do
  ...
  # continue as usual
  ...
end

Be sure to commit your .rbenv-version file in your project repository.

Git: removed the :revision setting

The :revision setting has been removed in Mina v0.2.0. This used to allow you to deploy any given Git branch, tag, or commit.

It has now been superceded by the :commit and :branch settings. To deploy a branch, set the :branch setting:

set :branch, 'master'

And to deploy a given commit, set the :commit setting:

set :commit, '2f19299a'

The reason for this change is that Git deploys are now optimized to be much faster when branches are specified.

Git: the default branch is now ‘master’

In Mina v0.1.x, the default deploy behavior is to deploy whatever the current commit is in your Git working repository.

In 0.2.0, the default is now the master branch. To change this, change the :branch setting:

set :branch, 'deploy'

The ‘deploy:link_shared_paths’ task

The deploy:link_shared_paths task has been existing since Mina v0.1.x, but was not documented.

To make certain directories/files shared between different releases, first specify them in the :shared_paths setting:

set :shared_paths, ['log', 'config/database.yml']

And link them in your deploy script by invoking deploy:link_shared_paths:

task :deploy => :environment do
  deploy do
    invoke :'git:clone'
    invoke :'deploy:link_shared_paths'
    ...
    ...
  end
end

New ‘:environment’ task convention

Mina introduces a new recommended convention of defining an :environment task to do initializations used for every command.

It is often used to load RVM or rbenv so that it will be available in mina deploy, mina rake[db:migrate], and other similar tasks.

Define the task in your deploy script like so:

task :environment do
  invoke :'rbenv:load'
end

Then make the deploy task depend on it:

task :deploy => :environment do
  ...
end

This instructs Rake (or rather, Mina) to load the :environment task before deploying.

This is entirely optional, but highly recommended.