But the answers are spread out and distributed randomly. Plus, I can only see “The program ‘______’ is currently not installed. You can install it by typing: sudo apt-get install ______” so many times before I lose interest and put off the task.

So, to prevent future headaches and help all of us out, I put together a how-to that can take a new Rails system from zero to code in a few minutes (depending on network speed) instead of half a day. With no further ado,

Setting up an Ubuntu box for Rails Development (including virtual machines)

Update everything

$ sudo aptitude update && sudo aptitude dist-upgrade

Install necessary packages

$ sudo aptitude install build-essential vim \
  vim-runtime git-core subversion libsqlite3-dev

We have projects in git (the newer ones) and svn, so we have to be able to switch fluidly between the two.

And I’m not trying to start a flame war, but Vim is the first choice for Rails development. You don’t have to take my word for it; Jamis Buck, Tim Pope, and Adam Lowe all say the same. I recommend the NERDTree, FuzzyFinderTextMate, BufExplorer, and rails.vim plugins if nothing else.

Install ruby

$ sudo aptitude install ruby1.8 ruby rdoc ruby1.8-dev \
  libpgsql-ruby1.8 libmysql-ruby1.8 irb libopenssl-ruby

Get rubygems from source. http://docs.rubygems.org/

$ wget http://rubyforge.org/frs/download.php/60718/rubygems-1.3.5.tgz

$ tar xzvf rubygems-1.3.5.tgz

$ cd rubygems-1.3.5

$ sudo ruby setup.rb

$ sudo ln -s /usr/bin/gem1.8 /usr/bin/gem

$ sudo gem update --system

Update ~/.gemrc (at least the :sources: chunk)

---
gem: --no-ri --no-rdoc
:benchmark: false
:verbose: true
:backtrace: false
:update_sources: true
:sources:
- http://gemcutter.org
- http://gems.rubyforge.org/
- http://gems.github.com

Install and setup Passenger (optional)

$ sudo apt-get install apache2-prefork-dev

$ sudo gem install passenger

$ sudo passenger-install-apache2-module

and follow the instructions passenger gives you. Most folks in the office run some form of an Apache-Passenger stack for development purposes. I can explain how that setup works in a future post.

Install geminstaller

$ sudo gem install geminstaller

Almost all of our legacy projects use geminstaller to manage gem dependencies. In the future, new projects will be moving to Bundler, but legacy projects matter and upgrading subsystems is not always justified.

“If it ain’t broke, don’t fix it” and the corollary: “because you probably won’t be able to bill it to the client” both apply.

Install common packages (optional, may be required by projects)

$ sudo aptitude install imagemagick

$ sudo gem install utility_belt open_gem redgreen

The first (imagemagick) is used by the Paperclip gem to manage files attached to Rails models. The second are tools that make Rails development more manageable on the command line. I highly recommend them. Besides, I’ve been sneaking redgreen in as a test dependency on our projects, so if you’re a developer here you’ll have to install it anyways.

Create an ssh key (follow instructions)

$ ssh-keygen

EXAMPLE PROJECT

All the stuff above won’t let you test-code-deploy without hassles, so here’s a sample run through of what the last mile of project-specific setup looks like.

Get the project. SVN, Git, whatever. Go to it.

$ svn co rails-project

$ cd rails-project

Run geminstaller

$ sudo geminstaller                                 # normal

$ sudo geminstaller -c config/test/geminstaller.yml # test env

Install necessary aptitude packages

$ sudo aptitude install texlive-latex-base

Don’t ask.

Create the test database

Mysql:

$ rake RAILS_ENV=test db:create

Postgres (using your username or DB username in place of “username”):

$ sudo -u postgres psql

postgres=# CREATE USER username SUPERUSER;

postgres=# CREATE DATABASE username OWNER username;

If you get an error regarding PGconn.quote_ident (Rails 2.3.x on Ubuntu 8.04) patch activerecord-2.3.4/lib/active_record/connection_adapters/postgresql_adapter.rb and add the following:

def PGconn.quote_ident(name)
  %("#{name}")
end

immediately after the “class PGresult” definition at the top of the file. Once that’s all done, the following:

$ rake RAILS_ENV=test db:create

$ rake RAILS_ENV=test db:schema:load

$ rake RAILS_ENV=test test

should work.

go have fun, write code, blow our minds

So that’s how we roll. Awkward requirements will still crop up as we pick up new projects (or very old projects) so you’ll always need a bit of apt/gem fu to get you through the day. Leave questions here or drop me a line at adam@smartlogicsolutions.com or http://twitter.com/abachman.

“Byobu is a Japanese term for decorative, multi-panel screens that serve as folding room dividers. As an open source project, Byobu is an elegant enhancement of the otherwise functional, plain, practical GNU Screen.”

https://wiki.ubuntu.com/MeetingLogs/openweekKarmic/Byobu

SSH into your server and install the two packages:

sudo apt-get install byobu landscape-common update-motd

Next, run byobu-config:

Change byobu settings with byobu-config

You can change Byobu’s colors if you’d like. I like the “dark” theme.

The important setting to change is the last one: “Byobu currently does not launch at login“. Select that and press return. Now you can go back to the menu and exit byobu-config (tab to the exit choice and hit return).

Now log out and log back in again. You’ll now access Byobu automatically.

Byobu as your session manager

The new MOTD (that’s “Message of the Day”, which is the text that is displayed when you login) has system information, thanks to landscape-common. This will let you know if your almost out of memory or disk space, or if you’re under heavy load.

Now let’s look at the information Byobu provides. The bottom row of Byobu contains, from left to right, your Distribution logo and name, uptime, load, cpu frequencies, ram amount and usage, and the date.

The upper row are your windows. Press F2 to create a new window. Along the bottom of the screen you’ll now see two entries in the top row of the footer. Press F3 to move to the previous window and F4 to move to the next window.

Press F8, then give the window a name, like “echo”. I like to name each tab with the task I’m doing, like “console”, “mysql”, and “top”.

You can press F7 to enter copy/scrollback mode. Use the arrow and page-up/down keys to move around your session. Press the spacebar to start copying. Now move your cursor somewhere else. Then press space again to copy the selection. Byobu doesn’t have a paste hotkey, so you have to use the screen hotkey, which is CTRL-a ] (thats CTRL-a, then let go of control and press ]).

You can press F12 to quickly lock your terminal, to grab a quick cup of coffee (or read this blog!).

Let’s explore how to maintain a session. Issue the following command:

echo hi

That will print out “hi” on the screen. Now let’s exit this session. Press the Byobu hotkey F6 to “Detach” from Byobu.

You’ll notice you’re still logged in, this is because Byobu is an application that runs on top of your session. So now you have to exit again to get back to your local machine.

Now SSH back into your machine. You’ll notice that command is still on the screen! “Detaching” does not end your session, it just detaches you from it. That means you can log in, run a long running task, and then Detach and come back in the morning when your task is done.

For extended information on Byobu, check out its Ubuntu Man Page.

I wanted to preview my HTML emails without having to fill up my online email inboxes with tons of email (and then I’d have to make filters too). I also didn’t want to manage actually sending real email. So, I set up my machine for local delivery. Read on for instructions.

I am running Ubuntu 9.04, however these instructions should be fine at least back to 8.04.

Step 1 – Install Postfix

sudo aptitude install postfix

During the install, choose “Local Delivery Only”

Step 2 – Configure Evolution for Receiving Locally

Open up Evolution “Applications->Internet->Evolution Mail”

Set up a new account and choose local delivery. When it asks you for a path, put in:

/var/mail/<username>

Note that this path may not exist if you’ve never received mail.

Step 3 – Configure Sanitize Email

In your rails test environment.rb put:

config.action_mailer.delivery_method = :sendmail

Then, in the initializer where you set up sanitize email:

ActionMailer::Base.sanitized_recipients = ["@"]
ActionMailer::Base.local_environments = %w( test )

If you need to know your username or hostname, just open up a terminal. The command “whoami” will give you your username, and “hostname” will give you the hostname.

Step 4 – Run your tests

Now, run your rails tests. You should have a test for every email you send, and that should trigger them to be sent locally. You may have to tell Evolution to Send/Receive. Keep in mind your tests will probably fail because they will expect email to be in test mode.

Step 5 – Set it back

Remember, when you’re done previewing your email, reset config.action_mailer.delivery_method!

  sudo gem install environmentalist

The only substantial change in this release is that we moved the loading of postboot.rb to the bottom of the boot.rb file as opposed to the top of config/environment.rb. This was necessary because common db rake tasks like db:create and db:drop stopped loading the environment in 2.3.2.

As a recap, environmentalist provides an executable that converts a rails app’s config structure. The basic idea is that environments themselves are now first-class citizens, allowing you to create several environments (e.g. staging, prodtest, demo, etc.) in a clean, organized fashion. Each environment is given its own folder where it can store its own set of configuration files (think mongrel configs, apache configs, etc.) without polluting the top-level config/ directory.

The primary motivation for me to make these changes stemmed from the need to have several deployable environments. The standard set of rails environments (development, test, production) simply just don’t cut it for me. It’s important for us to be able to deploy to staging, demo and even production-test environments. When including server configurations (e.g. a Passenger config snippet, or a mongrel_cluster config snippet), I’ve often had to use unique configurations for each deployable environment. Consequently, my config/ directory quickly became polluted with files such as: apache_prod.conf, apache_staging.conf, apache_demo.conf. Furthermore, it also requires special care when deployment comes around.

After manually handling this process for about a dozen apps, I decided to knock out an executable that would take care of this for me. Alas, environmentalist was born!

The basic notion behind environmentalist is that application/server configuration should be centered around environments. Rails has done this to an extent (there is a config/environments directory), but these simply contain a ruby script that ties into the initialization of an application. There’s no capacity for defining server/environment configuration outside of the scope of rails.

The gem installs a script that can handle both brand new applications as well as apps that have been in development for any period of time. The gem itself is only about 100 lines of ruby shell code that shifts your files around. In psuedo-code, it looks as such:

1. Create directories for each environment, e.g. config/development, config/test, etc.
2. Copy old environment files (config/environments/development.rb) to new structure (config/development/environment.rb)
3. Remove the old config/environments directory
4. Install config/postboot.rb # this file just overrides the default paths in Rails that are affected by our structural changes
5. Update config/environment.rb to include config/postboot.rb immediately after config/boot.rb
6. Break database.yml out into separate files. config/database.yml becomes config/development/database.yml, config/test/database.yml, etc.

The script is intended to handle the case where any or all of these steps have already been completed. In other words, running the script repeatedly on a particular project should not cause any damage.

Probably the most surprising aspect of this is the fact that I break out a database.yml file for each environment. I’ve made this argument before, and I encourage you to read it. The gist is this: despite the concern some have in the community about including database credentials in your repository, the fact is if you lock down your box, it doesn’t really matter (don’t allow access to your database server outside of a closed network, hello iptables!). And it’s certainly very convenient to have credentials for your deployable apps right in your config directory. This also allows us to separate our local credentials (development, test) — which have no business going into the repository — from our remote credentials. Database.yml problem solved!

For us, this restructuring achieves several other efficiencies. Two other gems I have (capistrano-extensions and passenger-recipes) take advantage of this structure to allow me to more easily create extra deployable environments. SmartLogic has reached a point now where it’s extremely helpful for us to deploy demo versions of almost all of our apps. With just a little bit of care taken upfront (and a demo server), we can now get this functionality extremely easily across the board.

This is great, how can I have it?

Well you can grab the gem off of github. I don’t actually have the gem hosted there (I use rake to dynamically build my gemspec, and I haven’t figured out how to allow github to build my gem without hard-coding version numbers and other values into my .gemspec file….any suggestions would be welcome!). The following steps will install the gem.

$> git clone git://github.com/jtrupiano/environmentalist.git
$> cd environmentalist
$> rake gem
$> sudo gem install pkg/environmentalist-0.1.0.gem

How do I use it?

An executable named “environmentalize” is installed when the gem is installed.

/path/to/my/rails/project$> environmentalize

Or, if you’re not in the root of your project:

~$> environmentalize path/to/rails/root

For completeness (and so you don’t have to download the source), I wanted to include the contents of postboot.rb:

# Be sure to restart your server when you modify this file.
 
rails_env = ENV['RAILS_ENV'] || 'development'
 
env_dir  = File.join(RAILS_ROOT, 'config', rails_env)
db_file  = File.join(env_dir, 'database.yml')
env_file = File.join(env_dir, 'environment.rb')
 
unless File.exists?(env_dir)
  puts "#{env_dir} environment directory cannot be found."
  exit(1)
end
 
unless File.exists?(db_file)
  puts "#{db_file} is missing.  You cannot continue without this."
  exit(1) # exit with an error code
end
 
unless File.exists?(env_file)
  puts "#{env_file} environment file is missing." 
  exit(1)
end
 
# Now, let's open up Rails and tell it to find our environment files elsewhere.
module Rails
  class Configuration
 
    def database_configuration_file
      File.join(root_path, 'config', environment, 'database.yml')
    end
 
    # The path to the current environment's file (development.rb, etc.). By
    # default the file is at <tt>config/environments/#{environment}.rb</tt>.
    def environment_path
      "#{root_path}/config/#{environment}/environment.rb"
    end
  end
end