Win/Mac/Linux Compatible Capistrano Recipe for Students of your Rails Course

README.markdown

TODO

• Include basic Gemfile
• Include Apache config
• Specify available tasks
• How to setup the students' PCs

Introduction

When giving a course based on Ruby on Rails, you will have many students coming from different backgrounds, using different Operating Systems, so you want their experience to be as smooth as possible. Deploying applications to the class server can be a pain in other frameworks, but in Rails, using Capistrano and Bundler, it is actually quite easy. This deploy configuration file for Capistrano intends to be as compatible with different OSs, as easy to use, and as complete as possible.

Requirements and Assumptions

This deploy file assumes a couple of things about the different technologies used, so you'll have to configure it to your own needs as necessary. Namely, it assumes:

• You have a Linux web server running Apache and Passenger to serve the Rails apps, with the configuration file attached below.
• That your students use SVN for version control (most people understand and know how to use SVN, and you might not want to spend time teaching how to use Git).
• SQLite3 for the database management system.
• If students are working alone, each gets his own username in the Linux server. If working in groups, each group gets his own username.
• One application per student (or one application per group).

Setup

There are some values that will be changed by you, the teacher, and some others by your students... unless you want to give each student their deploy file pre-configured.

As a teacher you must set:

• domain: The domain of the Linux server running Apache (and hosting the SVN repo)
• applicationdir: The directory where the students' apps will be stored in the server (defaults to $HOME/www).
• repository: The URL to the students' SVN repositories.

Students must set:

• user: Their username in the server.
• application: Their application's name (as stored in the SVN repo)
• uploads_dir: The directory name where uploads are saved (defaults to "system").

Available Tasks

TODO

Credit

This deploy.rb file was created by Hernán Schmidt (@lagartoflojo) with the help of various resources found around the web, which are credited where appropriate. This same file was used by the students of the course Tecnologías y Aplicaciones del WWW (Tecnologies and Applications of the WWW) in the first semester of 2011, given by professor Jaime Navón in the Pontificia Universidad Católica de Chile (http://www.puc.cl), which introduces students to the creation of Web Applications and Ruby on Rails.

deploy.rb

require 'bundler/capistrano'
###########################
## STUDENT CONFIGURATION ##
###########################
# Before you can get your application running on the server,
# you must change a couple of lines below.

# Here, you must replace MY_USERNAME with the username assigned
# to you in the class server.

set :user, 'MY_USERNAME'

# Next, change EXAMPLE to the name you gave your Rails application
# when you created it.
# For example, if you ran the following command to generate your app:
#   rails new tutorial
# then replace EXAMPLE with tutorial.

# This name must match the name of the directory where your 
# app is in the SVN repository.
# For example: https://rails.server.com/user1/tutorial

set :application, 'EXAMPLE'

#################################
## OPTIONAL CONFIG FOR UPLOADS ##
#################################
# When you give the users of your app the ability to upload their
# own files (like avatars, for example), they will get lost between
# one deploy and the next, so you will want to save them in the
# "shared" directory, rather than in "releases". To do this,
# set the name of the upload directory below.

set :uploads_dir, "system" # system is default for paperclip.



###########################
## TEACHER CONFIGURATION ##
###########################
# The following lines have been configured by your teacher,
# so you don't have to change them.

# Server domain
set :domain, 'YOUR.DOMAIN.HERE'

# Where the app will be in the user's home directory.
set :applicationdir, "/home/#{user}/www"

# Where the SVN repositories are located.
set :repository, "https://#{user}@#{domain}/svn/#{user}/#{application}"

#############################
## NO NEED TO CHANGE THESE ##
#############################

# Server config
server domain, :web, :app, :db, :primary => true

# Deploy directory
set :deploy_to, applicationdir
set :deploy_via, :export

# Database path
set(:shared_database_path) {"#{shared_path}/databases"}

# Other configurations.
default_run_options[:pty] = true  # Ignorar errores en consola de Windows
set :chmod755, "app config db lib public vendor script script/* public/disp*"
set :use_sudo, false

# Restart passenger after deploys.
namespace :deploy do
  task :start do ; end
  task :stop do ; end
  task :restart, :roles => :app, :except => { :no_release => true } do
    run "#{try_sudo} touch #{File.join(current_path,'tmp','restart.txt')}"
  end
end

# These tasks maintain the SQLite3 database between deploys.
# Source: http://www.bagonca.com/blog/2009/05/09/rails-deploy-using-sqlite3/
namespace :sqlite3 do
  desc "Generate a database configuration file"
  task :build_configuration, :roles => :db do
    db_options = {
      "adapter"  => "sqlite3",
      "database" => "#{shared_database_path}/production.sqlite3"
    }
    config_options = {"production" => db_options}.to_yaml
    put config_options, "#{shared_database_path}/sqlite_config.yml"
  end
 
  desc "Links the configuration file"
  task :link_configuration_file, :roles => :db do
    run "ln -nsf #{shared_database_path}/sqlite_config.yml #{release_path}/config/database.yml"
  end
 
  desc "Make a shared database folder"
  task :make_shared_folder, :roles => :db do
    run "mkdir -p #{shared_database_path}"
  end

  desc "Drop SQLite3 database"
  task :drop, :roles => :db do
    run "rm #{shared_database_path}/production.sqlite3"
  end

  desc "Load the database with seed data"
  task :seed do
    run "cd #{current_path}; rake db:seed RAILS_ENV=production"
  end
end

after "deploy:setup", "sqlite3:make_shared_folder"
after "deploy:setup", "sqlite3:build_configuration"
after "deploy:update_code", "sqlite3:link_configuration_file"

# Bundler 1.0 on Windows generates a Gemfile.lock that specifies mingw as the platform,
# so when the app is deployed on a Linux server, Bundler fails to install de Linux gems.
# These tasks work around this bug.
# This bug should be fixed on Bundler 1.1.
on :start, "bundle:fix_gemfile"
namespace :bundle do
  desc "Fix Gemfile.lock to use *nix gems"
  task :fix_gemfile do
    gem_file = File.read("Gemfile")
    replace = gem_file.gsub(/(.*)gem (.*)win32(.*)\n/, "")
    File.open("Gemfile", "w") {|file| file.puts replace}
    gem_file_lock = File.read("Gemfile.lock")
    # remove windows specific gems
    replace = gem_file_lock.gsub(/(.*)win32(.*)\n/, "")
    # update the gems to have correct extensions
    replace = replace.gsub(/-x86-mingw32/, "")
    # store the correct platform
    replace = replace.gsub(/PLATFORMS\n x86-mingw32\n/, "PLATFORMS\n ruby\n")
    # remove any other instance of mingw
    replace = replace.gsub(/(.*)mingw(.*)\n/, "")
    File.open("Gemfile.lock", "w") {|file| file.puts replace}
    # commit Gemfile.lock to svn, i.e. svn ci Gemfile.lock if there is any changes
    run_locally 'svn ci Gemfile Gemfile.lock -m "updated Gemfile and Gemfile.lock with *nix version"'
  end
end

namespace :config do
  desc "Link shared files"
  task :symlink do
    run "rm -drf #{release_path}/public/#{uploads_dir}"
    run "ln -s #{shared_path}/#{uploads_dir} #{release_path}/public/#{uploads_dir}"
  end

  desc "Create uploads dir"
  task :make_upload_dir do
    run "mkdir #{shared_path}/#{uploads_dir}"
  end
end

before "deploy:symlink", "config:symlink"
after "deploy:setup", "config:make_upload_dir"