Class RailsInstaller
In: lib/rails-installer.rb
lib/rails-installer/commands.rb
lib/rails-installer/web-servers.rb
lib/rails-installer/databases.rb
lib/rails-installer/commands.rb
lib/rails-installer/databases.rb
lib/rails-installer/web-servers.rb
Parent: Object

Rails Application Installer

An installer for Rails applications.

The Rails Application Installer is designed to make it easy for end-users to install open-source Rails apps with a minimum amount of effort. When built properly, all the user needs to do is run:

   $ sudo gem install my_app
   $ my_app install /some/path

Users who need to install your .gem but don‘t have the right permissions can do this instead:

   $ export GEM_PATH=~/gems
   $ gem install -i ~gems my_app
   $ ~gems/bin/my_app install /some/path

Adding the installer to your application

(This example assumes that your program is called ‘my_app’. Change this to match your application‘s actual name)

First, create a small driver program and put it into bin/my_app. Here‘s a minimal example:

   #!/usr/bin/env ruby

   require 'rubygems'
   require 'rails-installer'

   class AppInstaller < RailsInstaller
     application_name 'my_app'
     support_location 'our shiny website'
     rails_version '1.1.6'
   end

   # Installer program
   directory = ARGV[1]

   app = AppInstaller.new(directory)
   app.message_proc = Proc.new do |msg|
     STDERR.puts " #{msg}"
   end
   app.execute_command(*ARGV)

This is a simple example; you can extend the installer to add new commands and install steps. See the examples/ directory for more complex examples.

Second, you‘ll need some schema files in db/schema.*.sql. The schema_generator plugin can generate these automatically from your migrations:

   $ sudo gem install schema_generator
   $ ./script/generate schemas
   $ svn add db/schema.*.sql
   $ svn add db/schema_version

Third, build a .gem file. Make sure that it depends on the rails-app-installer GEM. Make sure that the generated schema files and the installer that you put in bin/ are included in your .gem, and the gem knows that bin/my_app is supposed to be executable. Here‘s an example from Typo‘s .gemspec. This may be more complex then you need.

   $:.unshift '../lib'
   require 'rubygems'
   require 'rake'

   spec = Gem::Specification.new do |s|
     s.name = "typo"
     s.version = "4.0.2"
     s.summary = "Modern weblog engine."
     s.has_rdoc = false

     s.files = Dir.glob('**/*', File::FNM_DOTMATCH).reject do |f|
        [ /\.$/, /config\/database.yml$/, /config\/database.yml-/,
        /database\.sqlite/,
        /\.log$/, /^pkg/, /\.svn/, /^vendor\/rails/,
        /^public\/(files|xml|articles|pages|index.html)/,
        /^public\/(stylesheets|javascripts|images)\/theme/, /\~$/,
        /\/\._/, /\/#/ ].any? {|regex| f =~ regex }
     end
     s.require_path = '.'
     s.author = "Tobias Luetke"
     s.email = "tobi@leetsoft.com"
     s.homepage = "http://www.typosphere.org"
     s.rubyforge_project = "typo"
     s.platform = Gem::Platform::RUBY
     s.executables = ['typo']

     s.add_dependency("rails", "= 1.1.6")
     s.add_dependency("rails-app-installer", ">= 0.1.2")
   end

   if $0==__FILE__
     Gem::manage_gems
     Gem::Builder.new(spec).build
   end

Using your .gem

You can test your new gem by running ‘sudo gem install ./my_app-1.0.0.gem’. Once you‘re happy with it, upload it to Rubyforge and it‘ll automatically be added to the master gem index.

Users should be able to download and install it using the commands at the top of this document.

Non-standard install options

By default, the installer uses SQLite3 and Mongrel when installing your app. The user can override this at install time with some flags. Examples:

   # install using SQLite3 and Mongrel
   $ my_app install /some/path

   # install using MySQL and Mongrel
   $ my_app install /some/path database=mysql db_user=my_app db_name=my_app db_host=localhost db_password=password

   # install using PostgreSQL and Mongrel
   $ my_app install /some/path database=postgresql db_user=my_app db_name=my_app db_host=localhost db_password=password

   # install using SQLite3 and mongrel_cluster
   $ my_app install /some/path web-server=mongrel_cluster threads=4

Methods

Included Modules

FileUtils

Classes and Modules

Class RailsInstaller::Command
Class RailsInstaller::Database
Class RailsInstaller::InstallFailed
Class RailsInstaller::WebServer

Attributes

config  [RW] 
install_directory  [RW] 
message_proc  [RW] 
source_directory  [RW] 

Public Class methods

The application name. Set this in your derived class.

Which Rails version this app needs. This version of Rails will be frozen into vendor/rails/

The support location. This is displayed to the user at the end of the install process.

Public Instance methods

The application name, as set by application_name.

The path to the config file that comes with the GEM

Backup the database

The path to the installed config file

Copy files from the source directory to the target directory.

Copy a specific gem‘s contents.

Copy one file from source_directory to install_directory, creating directories as needed.

Create all default config files

Create the default database.yml

Create required directories, like tmp

Create the initial SQLite database

Execute a command-line command

Expand configuration template files.

Locate the source directory for a specific Version

Clean up file and directory permissions.

Freeze to a specific version of Rails gems.

Get the current schema version

Compute the different between two hashes. Returns four hashes, one contains the keys that are in ‘b’ but not in ‘a’ (added entries), the next contains keys that are in ‘a’ and ‘b’, but have different values (changed). The third contains keys that are in ‘b’ but not ‘a’ (added). The final hash contains items that are the same in each.

Install Application

Another install hook; install_post_hook runs after the final migration.

The easy way to add steps to the installation process. install_pre_hook runs right after the DB is backed up and right before the first migration attempt.

The default install sequence. Override this if you need to add extra steps to the installer.

Display a status message

Migrate the database

Pre-migrate the database. This checks to see if we‘re downgrading to an earlier version of our app, and runs ‘rake migrate VERSION=…’ to downgrade the database.

Decide which Rails version to freeze

Load a yaml file

Restore the database

Run Rails tests. This helps verify that we have a clean install with all dependencies. This cuts down on a lot of bug reports.

Save config settings

Pick a default port number

Find all files in a directory tree and return a Hash containing sha1 hashes of all files.

Start application in the background

Stop application

Call system, ignoring all output.

[Validate]