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
(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
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.
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
config | [RW] | |
install_directory | [RW] | |
message_proc | [RW] | |
source_directory | [RW] |
The support location. This is displayed to the user at the end of the install process.
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.
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.
Run Rails tests. This helps verify that we have a clean install with all dependencies. This cuts down on a lot of bug reports.