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:
- Upgrade
rails
gem - Change your
environment.rb
so it saysRAILS_GEM_VERSION = '2.3.9'
- 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 toshared/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
-
Add "whenever" to your
Gemfile
:group :deploy do gem 'whenever', require: false end
-
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
...
Update: Shell script to deploy changes to production and not shoot yourself in the foot
deploy-to-production
now calls Capistrano with bundle exec
since we started to bundle Capistrano in all projects.
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...