How to use the Capistrano 2 shell to execute commands on servers

Capistrano 2 brings the shell command which allows you to run commands on your deployment targets.
There is also invoke to run a command directly from your terminal.

Both commands allow running Capistrano tasks or shell commands, and scope to individual machines or machine roles.

Unfortunately Capistrano 3 does not include these commands any more.

cap shell

Basics

First of all, spawn a Capistrano shell (we're using the multistage extension here):

$ cap staging shell

In your "cap" shell you can now run Capistrano ta...

Common mistakes when storing file uploads with Rails

1. Saving files to a directory that is not shared between deploys or servers

If you save your uploads to a made up directory like "RAILS_ROOT/uploads", this directory goes away after every deploy (since every release gets a new). Also this directory is not shared between multiple application servers, so your uploads are randomly saved to one local filesystem or another. Fixing this afterwards is a lot of fun.

Only two folders are, by default, shared between our application servers and deployments: "RAILS_ROOT/storage" and `"RAILS...

Upgrading Rails 2 from 2.3.8 through 2.3.18 to Rails LTS

This card shows how to upgrade a Rails 2 application from Rails 2.3.8 through every single patch level up to 2.3.18, and then, hopefully, Rails LTS.

2.3.8 to 2.3.9

This release has many minor changes and fixes to prepare your application for Rails 3.

Step-by-step upgrade instructions:

  1. Upgrade rails gem
  2. Change your environment.rb so it says RAILS_GEM_VERSION = '2.3.9'
  3. Change your ...

Clean up application servers when deploying

Our development process makes us deploy very often. As the number of releases grows, junk clogs up the hard drive of our application servers:

  • Old release code
  • Old tmp folders with compiled view templates etc.
  • Precompiled assets (Javascripts, images...) that no longer exist. When using the asset pipeline, Capistrano will symlink the public/assets directory to shared/assets. This is cool since we can still serve previous assets after a new release, in the window where browser caches might still have references to old assets. But i...

Capistrano: Bundler stalls and asks for "Username"

Given you use Capistrano together with bundler to automatically install your gems when deploying.

I recently had the problem that Capistrano stalled like this:

[err :: host.name.tld] Username:

It turned out that I this originated from GitHub. We had a gem in our Gemfile that explicitly pointed to a GitHub URL like that:

gem 'foogem', :git => 'https://github.com/blubb/foogem.git'

The URL was returning a 404 which caused the problems. You have to get another gem or point to a fork on GitHub.

Geordi: run a capistrano task on all stages

Geordi now has a script that runs capistrano with all known deploy targets (i.e. staging, production...).

Use with

geordi capistrano deploy:migrations

or

geordi capistrano deploy

The abbrevation geordi cap ... works as well.

Customize tokenization of the MySQL FULLTEXT parser

The way MySQL's FULLTEXT tokenizer splits text into word tokens might not always be what you need. E.g. it splits a word at period characters.

Since the tokenizer has near-zero configuration options (minimum word length and stopwords list), you need to hack it. There are three options available.

Option 1: If you like pain

Write a Full-Text parser plugin in C.

Option 2: Make the problem go away

Normaliz...

Cronjobs: "Craken" is dead, long live "Whenever"

Our old solution for cronjobs, the "craken" plugin, is no longer maintained and does not work on Rails 3.2+.

We will instead use the whenever gem.

"Whenever" works just like "craken", by putting your rake tasks into the server's cron table. Everything seems to work just like we need it.

Installation for new projects

  1. Add "whenever" to your Gemfile:

     group :deploy do
       gem 'whenever', require: false
     end
    
  2. Add it to your config/deploy.rb:
    ...

Capistrano: How to find out which version of your application is currently live

When deploying, Capistrano puts a REVISION file into your application's release directory. It contains the hash of the commit which was deployed.

If you want to know the currently deployed release, simply SSH to a server and view that file.

$ cat /var/www/my-project/current/REVISION
cf8734ece3938fc67262ad5e0d4336f820689307

Capistrano task

When your application is deployed to multiple servers, you probably want to see a result for all of them.
Here is a Capistrano task that checks all servers with the :app role.

Mysql/Mysql2 agnostic database.yml

If you upgrade to the mysql2 gem, you will run into the problem that the server's database.yml (which is usually not under version control) needs to change exactly on deploy.

You can however make your database.yml work for mysql and mysql2 at the same time. Simpy do this

production:
   adapter: <%= defined?(Mysql2) ? 'mysql2' : 'mysql' %>
   #...

Rails asset pipeline: Why relative paths can work in development, but break in production

The problem

When using the asset pipeline your assets (images, javascripts, stylesheets, fonts) live in folders inside app:

app/assets/fonts
app/assets/images
app/assets/javascripts
app/assets/stylesheets

With the asset pipeline, you can use the full power of Ruby to generate assets. E.g. you can have ERB tags in your Javascript. Or you can have an ERB template which generates Haml which generates HTML. You can chain as many preprocessors as you want.

When you deploy, Rails runs assets:precompile...

Fix capistrano errors: "no such file to load -- net/ssh/authentication/agent/socket" or "uninitialized constant Net::SSH::KnownHosts::SUPPORTED_TYPE"

There is a conflict between current capistrano versions and the 2.5.1 net-ssh gem. Make sure you upgrade to 2.5.2, then it should work again.

Bundle capistrano

Capistrano recently had some API changes that can results in deploys not working when running with old deploy.rb files.

So let's bundle it. Put capistrano into your Gemfile, like this:

# Gemfile

group :deploy do
  gem 'capistrano'
  gem 'capistrano_colors'
end

It's possible you need to do a bundle update net-ssh to get things running.

Now double check that all your custom hooks are actually still called. One candidate might be an after deploy:symlink hook that has been renamed into `after deploy:creat...

Fix Capistrano warnings: Missing public directories

I got these warnings while deploying a Rails 3.2 app with asset pipeline enabled:

*** [err :: host.tld] find: `/opt/www/hollyapp.com/releases/20120503115342/public/images': No such file or directory
*** [err :: host.tld] find: `/opt/www/hollyapp.com/releases/20120503115342/public/stylesheets': No such file or directory
*** [err :: host.tld] find: `/opt/www/hollyapp.com/releases/20120503115342/public/javascripts': No such file or directory

Folders like public/javascripts might not exist if you're using the asset pipeline (...

Shell script to deploy changes to production and not shoot yourself in the foot

Geordi, our collection of command line tools, has been extended by another command deploy-to-production. This script encapsulates the following workflow:

  • Pull the production branch.
  • Show which commits from the master would make it to production with this deploy.
  • Ask if you want to proceed.
  • If yes, merge the master into the production branch, push and deploy with bundle exec cap production deploy:migrations

The script will ask you for the names of your master branch, production branch an...

Gherkin: Error during installation

When trying to install the gherkin gem, you might encounter an error with the following lines:

ERROR:  Error installing gherkin:
	ERROR: Failed to build gem native extension.
...
checking for main() in -lc... yes
creating Makefile
...
cc1: all warnings being treated as errors
Makefile:150: recipe for target 'gherkin_lexer_ar.o' failed
make: *** [gherkin_lexer_ar.o] Error 1
...

If upgrading is not an option, configure build options for gherkin:

bundle config --local build.gherkin --with-cflags=-w

Your .bundle/config fi...

Gatekeeping: Guide for developer

If your project manager wants to do gatekeeping on a project, as a developer you need to follow the following guidelines (e.g. by using something like this issue checklist template).

In order to reduce the number of rejects we get from clients, we want to review all code written before it goes to the staging server.

Note

This process is tailored to our specific needs and tools at makandra. While it will certainly not apply to all (especially larger teams), we think it...

Gatekeeping: Guide for gatekeeper

If you're responsible for gatekeeping in a projects, here is a guide, what to do.
In order to reduce the number of rejects we get from clients, we want to review all code written before it goes to the staging server.

Note: This process is tailored to our specific needs and tools at makandra. While it will certainly not apply to all (especially larger teams), we think it is a helpful starting point.


First, read the [Gatekeeping for developers](https://makandracards.com/makandra/6579-gatekeeping-guide-for...

Make Capistrano use SSH Key Forwarding

When deploying code with Capistrano (depending on your configuration) at some point Capistrano tries to check out code from your repository. In order to do so, Capistrano connects to your repository server from the application server you're deploying to with SSH. For this connection you can use two SSH keys:

  • the user's ~/.ssh/id_rsa [default]
  • the very same key you used for connecting to the application server - forwarded automatically to the git repository.

If you prefer the second way, add this to deploy.rb:

ssh_options[:forwar...

How to revert features for deployment, merge back, and how to stay sane

Removing features and merging those changes back can be painful. Here is how it worked for me.\
tl;dr: Before merging back: reinstate reverted features in a temporary branch, then merge that branch.

Scenario

Consider your team has been working on several features in a branch, made many changes over time and thus several commits for each feature.\
Now your client wants you to deploy while there are still stories that were rejected previously and can't be deployed.
...

Get color in the Capistrano output

Note: capistrano_colors was merged into Capistrano starting from v2.13.5. However, this requires Ruby 1.9+.

If you cannot upgrade Capistrano to 2.13.5+ (e.g. because you're still running on Ruby 1.8), simply put capistrano_colors into your Gemfile and require 'capistrano_colors' in your config/deploy.rb file.

Error "The --deployment flag requires a Gemfile.lock. Please make sure you have checked your Gemfile.lock into version control before deploying."

If you get this error while deploy and you are sure the Gemfile.lock is in the version control check your releases directory.

This error can occur if someone/something copy a file or directory into your releases directory.

How to fix "unknown role" errors in Capistrano recipes

When you have a complex recipe setup with multistage deployment you may run into this error:

`role_list_from': unknown role `something' (ArgumentError)

Consider this task definition:

namespace :foo do
  task :bar, :roles => :something do
    # do crazy stuff
  end
end

Whenever we call foo.bar in our recipe, Capistrano will fail if you deploy to a stage where none of the servers has the role the error complains about, "something" in this case.

However, you can [hack around it](http://groups.google.com/group/ca...