I typically leverage rewrite rules to take my sites offline for maintenance. Most capistrano users will be familiar with the following Apache rewrite ruleset.

  RewriteCond %{REQUEST_URI} !\.(css|jpg|png)$
  RewriteCond %{DOCUMENT_ROOT}/system/maintenance.html -f
  RewriteCond %{SCRIPT_FILENAME} !maintenance.html
  RewriteRule ^.*$ /system/maintenance.html [L]

This ruleset matches requests for non-asset URL’s and renders a maintenance page if it exists on the filesystem. When capistrano users run cap deploy:web:disable REASON="site upgrade" UNTIL="2PM" a maintenance page is placed in public/system and this ruleset begins to kick in. Running cap deploy:web:enable will remove this page and the ruleset ceases to match.

We can replace this ruleset with the following Rack::Rewrite rule:

  # Ruby 1.8.x
  maintenance_file = File.join(RAILS_ROOT, 'public', 'system', 'maintenance.html')
  send_file /.*/, maintenance_file, :if => Proc.new { |rack_env|
    File.exists?(maintenance_file) && rack_env['REQUEST_URI'] !~ /\.(css|jpg|png)/
  }

This rewrite rule uses the send_file method to return the maintenance page, uses a rule guard (the :if proc) to check for the existence of the file, and accesses the rack environment directly (rack_env arg to the Proc) to check the request URI. Due to the shortcomings of the Ruby 1.8′s regular expression library (no negative lookahead), we have to leverage the rule guard to allow assets to continue to be served (css, jpg, png).

Using Ruby 1.9, this rule is simpler.

  # Ruby 1.9.x
  maintenance_file = File.join(RAILS_ROOT, 'public', 'system', 'maintenance.html')
  send_file /(.*)$(?<!css|png|jpg)/, maintenance_file, :if => Proc.new { |rack_env|
    File.exists?(maintenance_file)
  }

Users of 1.8.x can leverage Oniguruma to keep the rule simpler.

  # Ruby 1.8.x + Oniguruma
  maintenance_file = File.join(RAILS_ROOT, 'public', 'system', 'maintenance.html')
  send_file Oniguruma::ORegexp.new("(.*)$(?<!css|png|jpg)"), maintenance_file, :if => Proc.new { |rack_env|
    File.exists?(maintenance_file)
  }

Whenever Integrity would try to build my project, I’d get an error about rake not being able to be found: sh: rake: not found

This totally threw me. I had added it to /etc/environment

PATH="/opt/ruby/bin:$PATH"

and so it was certainly on my PATH:

john@john-ci:~$ echo $PATH
/opt/ruby/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

I had also added it to /root/.bash_profile so that root would have it picked up:

john@john-ci:~$ sudo su -
root@john-ci:~# echo $PATH
/opt/ruby/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

So why wasn’t Apache/Integrity picking it up? To seek this out, I opened up the Integrity source and edited /opt/ruby/lib/ruby/gems/1.8/gems/integrity-0.1.9.3/lib/integrity/project_builder.rb to output the values of `whoami` and $PATH to help me troubleshoot.

IO.popen("(echo `whoami` && echo $PATH && cd #{scm.working_directory} && $
          |output| build.output = output.read }

Doing this yielded the following output:

www-data
/usr/local/bin:/usr/bin:/bin

At this point, I wholly expected the PATH to not include /opt/ruby/bin, so this isn’t a surprise. But why is this being set?

The Real Problem

The real issue here was that I was trying to set the PATH in scripts that only get run when a shell is entered. Since apache starts up as a system process, it is not started from a shell, and does not have a PATH associated with it. In fact, if you open up /etc/init.d/apache, you’ll see on one of the first few lines that the PATH is distinctly set:

ENV="env -i LANG=C PATH=/usr/local/bin:/usr/bin:/bin"

This was precisely the PATH I was seeing when I hacked Integrity to output its PATH just prior to failing the Rake command. Now it’s fairly obvious that I just need to add in /opt/ruby/bin to the front of that PATH, and Integrity will be able to execute all of my ruby/rubygem executables (most importantly rake).

Recap of Steps to Install

1. Download and install REE
2. Create a symlink for /opt/ruby so it’s dead simple to upgrade when a new REE comes out: sudo ln -s /opt/ruby-enterprise-whatever-version-you-installed /opt/ruby
3. edit /etc/environment to add /opt/ruby/bin to your shell PATH : PATH=/opt/ruby/bin:$PATH
4. edit ~/.bash_profile to alias sudo so that sudo can inherit your environment : alias sudo='sudo env PATH=$PATH'
5. Reload your environment to pick up the new PATH: source /etc/environment && source ~/.bash_profile
6. Install Passenger: sudo gem install passenger && passenger-install-apache2-module
7. Install Integrity Gem: sudo gem install integrity
8. Install Integrity Home: sudo integrity install --passenger ~www-data/integrity
9. Install do_sqlite3 Gem: sudo gem install do_sqlite3
10. Prepare Integrity Database: cd ~www-data/integrity && sudo integrity migrate_db config.yml
11. Grant ownership of all integrity files to www-data: sudo chown -R www-data:www-data ~www-data/integrity
12. Create Apache config for Integrity: sudo nano -w /etc/apache2/sites-available/integrity:

    
      ServerName ci.yourdomain.com
      DocumentRoot /var/www/integrity/public
    
    

13. Enable the site: sudo ln -s /etc/apache2/sites-available/integrity /etc/apache2/sites-enabled/002-integrity
14. Edit /etc/init.d/apache2 and add /opt/ruby/bin to the PATH as described above: ENV="env -i LANG=C PATH=/opt/ruby/bin:/usr/local/bin:/usr/bin:/bin"
15. Restart Apache: sudo /etc/init.d/apache2 restart
16. Navigate to http://ci.yourdomain.com/ and start adding projects.

Boy, that was a mouthful. Please let me know if you’ve also been successful, and if there are any other steps you take to set up Integrity with REE and Passenger.