Slingshot

What

A gem for configuring and setting up Slingshot (full-stack, Ruby on Rails) Servers.

Installing

sudo gem install slingshot

The basics

This library is what is known as a “Task Library” for Capistrano. It’s a set of recipes, tasks, extensions and plugins that work with Capistrano to setup and configure a server for a Rails Application, quickly, and easily.

We have to admit, this gem was extracted out of the dozens and dozens of applications built by Highgroove Studios and deployed on Slingshot Hosting servers, but we assure you that you can use them on almost any server. In fact, we encourage you to do so, and report back bugs, fixes, and general comments.

In a nutshell:

• install slingshot gem
• capify your application:

  cap -A /your/app

• include the slingshot gem in your config/deploy.rb:

  require 'slingshot'

• customize your deploy.rb recipe
• run the setup task:

  cap setup

• bask in the glory of a fully setup rails application

The premise

Server setups should be scripted, repeatable, well-documented, and easy to change. The slingshot gem helps do that by consistently keeping all Rails specific server configuration files in one place.

We do this by overwriting the setup files every time on the server. Rather than manually hacking apache configurations, crontab jobs, monit confs, and mongrel configs, we script the generation of them, and can re-setup at any time.

Demonstration of usage

Let’s deploy an application. First, we apply the default capistrano recipes to (capify) our application:

cap -A /path/to/my/rails/app

Next, open up the config/deploy.rb, and require the mongrel cluster and slingshot gems:

require 'mongrel_cluster/recipes'
require 'slingshot'

We now need to configure a few variables, simply add these to the config/deploy.rb:

set :application,       "application" 
set :repository,        "http://svn.yourhost.com/#{application}/trunk" 

set :server_name,       'daytona.slingshothosting.com'
set :server_ip,         '1.2.3.4'
set :server_fqdn,       'daytona.slingshothosting.com'

set :domain_name,       'yourdomain.com'

set :user,              'deploy'
set :group,             'users'
set :password,          'password'

set :deploy_to,         "/var/www/apps/#{application}" 
set :deploy_username,   'deploy'
set :deploy_password,   'password'

set :svn_username,      'deploy'
set :svn_password,      'password'

set :database_username, 'deploy'
set :database_password, 'password'

set :mongrel_conf,      "#{current_path}/config/mongrel_cluster.yml" 

You can also optionally set a valid timezone such as EST, EST5EDT, CST6DT, MST, or PST8PDT (the default is GMT):

set :server_timezone,   'GMT'

Let’s do a pretend setup to see what happens:

cap setup -P

If you want to customize a task, simply take the task from the slingshot library, copy it and paste it into your config/deploy.rb.

• TODO: include / show a sample config/deploy.rb and some sample usages

If you’re ready to keep going, we suggest running the tasks in this order, to ensure they’re setup correctly:

cap setup
cap mysql_setup  # warning, this one is semi-detructive
cap update_code
cap symlink
cap migrate
cap cold_deploy
cap restart_web

• TODO: explain some tips n tricks, like the monit setup tasks, etc.
• TODO: add the initial steps to setting up a server (cap slingshot_setup, etc.)

Gem installation

You can setup additional gems using capistrano. Here are some examples:

  # this command:
  #  sudo gem install rails --include-dependencies
  # is: 
  gem.install 'rails'

  # this command:
  #  sudo gem install mysql --version $MYSQLGEM_VERSION -- --with-mysql-config
  # is: 
  gem.select 'mysql', :version => '2.7', :platform => 'ruby', :extra_params => '-- --with-mysql-config'

  # can also do a list  
  gem.install 'net-ssh capistrano termios rmagick RedCloth BlueCloth'

  # more examples:
  gem.select 'ferret', :version => '0.11.3', :platform => 'ruby'
  gem.select 'Hpricot', :version => '0.5', :platform => 'ruby'
  gem.install 'rmagick aws-s3 runt zentest diff-lcs'

You can put these in your own tasks to install gems using capistrano.

Some Variables you can Override

If you’re going to host multiple applications on the same server, there are a few variables you’ll want to override. Most importantly are the mongrel starting port and application name.

Here are some more totally optional variables. See the recipes themselves for more information.

# ssl certificates must live in the /path/to/apache/conf/ssl directory
set :configure_ssl, false  # set this to true to use SSL
set :ssl_certificate_file, "#{server_name}.pem" 
set :ssl_certificate_key_file, "#{server_name}.key" 
set :ssl_ca_certificate_file, 'sf_issuing.crt'

# set this to the correct db adapter and settings
set :database, "mysql" 
set :database_host, "localhost" 

# saves space by only keeping last 3 when running cleanup
set :keep_releases, 3 

# issues svn export instead of checkout
set :checkout, "export" 

# number of mongrel servers to start
set :mongrel_servers, 3

# mongrel starting port
set :mongrel_start_port, 8000

Help

No snazzy discussion group, forum, or lingr chat room yet, if you need help, just holler at the Highgroove Studios or Slingshot Hosting team.

trac site: http://trac.highgroove.com/deployment

License

This code is free to use under the terms of the MIT license.

Contact

Comments are welcome. Send an email to Charles Brian Quinn.

Charles Brian Quinn, 17th August 2007
Gem packager/webpage/scripts by Dr Nic
Theme extended from Paul Battley