deployer 0.1.1 → 0.1.2

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2009 Michael van Rooijen
+Copyright (c) 2010 Michael van Rooijen
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -0,0 +1,213 @@
+# Deployer
+
+Deployer is gem that enhances Capistrano to simplify the deployment of Ruby on Rails applications.
+
+It assumes you are using Passenger to serve your Ruby on Rails applications.
+
+
+## Getting Started
+
+install the gem
+
+    gem install deployer
+
+create a new Rails app
+
+    rails new my_application
+
+move into the Rails app and execute the "capify" and "enhancify" commands
+
+    cd my_application
+    capify .
+    enhancify .
+
+enhancify is a command, provided by deployer that will inject some code into the Capfile and replace the config/deploy.rb with the one used for *Deployer*. If the deploy.rb file already exists, it will simply rename it to "deploy.old.1.rb", and if that also exists it will rename it to deploy.old.2.rb, etc. etc. So you will never accidentally overwrite your initial deploy.rb file.
+
+This is what the deploy.rb looks like: "config/deploy.rb":http://github.com/meskyanichi/deployer/blob/master/setup/deploy.rb
+
+*Next, open the config/deploy.rb file and edit the following variables.*
+
+    set :appname,   "example.com"     # the name of your application
+    set :ip,        "123.45.678.90"   # the ip address of the production server
+    set :user,      "deployer"        # the user that will deploy to the production server
+    set :remote,    "origin"          # the remote that should be deployed
+    set :branch,    "production"      # the branch that should be deployed
+
+
+And *that's it!* You are now ready to do the following through *Deployer*:
+
+- Create a remote git repository (only works if on production server)
+- Push your initial commit to the remote repository
+- Create the production environment to where you will deploy your application to
+- And, of course, deploy and run your Rails application!
+
+Here is are the quick-reference comments of the config/deploy.rb file
+
+    # Quick Reference
+    # Configure the essential configurations below and do the following:
+    #
+    #   For more information:
+    #   http://github.com/meskyanichi/deployer 
+    #
+    #   Create Local and Remote Repository:
+    #   This will create a git repository on the deployment server
+    #   Will not work when using a remote location such as github.com, trunksapp.com
+    #     git init
+    #     cap deploy:repository:create
+    # 
+    #   Initial Deployment:
+    #     git add .
+    #     git commit -m "Initial commit for deployment"
+    #     git push origin [:branch]
+    #     cap deploy:initial
+    #     
+    #   Then For Every Update Just Do:
+    #     git add .
+    #     git commit -am "some other commit"
+    #     git push origin [:branch]
+    #     cap deploy
+    #
+    #   For a Full List of Commands
+    #     cap -T
+
+
+There are more tasks, but these will be your main commands. It's pretty straightforward.
+
+To list all commands:
+
+    cap -T
+
+
+### Automated Tasks
+
+*Deployer* will invoke various built-in tasks to try and deploy your application successfully.
+
+On the initial setup *cap deploy:initial* (this procedure only has to be performed once)
+
+- It will setup the production environment: releases and shared folder
+- It will populate the shared folder with the folders you specified in the deploy.rb file
+- It will sync your applications *database.yml* file to the shared/config folder
+
+And the deployment procedure that follows (*cap deploy*), does the following:
+
+- It will create a new folder in the releases folder and deploy your application to it
+- It will ensure that the shared folder has all the folders you specified in the *deploy.rb*
+- It will setup built-in symlink setups for your database.yml, production log
+- It will also setup any additional symlinks you may have specified inside the *deploy.rb* from the release folder to the shared folder
+- It will ensure all gems that are specified inside the Gemfile are installed.
+- It will ensure the database is present and migrated to the latest version
+- It will then perform any *custom* tasks you might have specified inside the *deploy.rb* file within the *after_deploy* method definition
+- It will then restart passenger (your application)
+
+So now the application has been deployed. For pushing new versions to the server you do the following:
+
+    git add .
+    git commit -m "new version commit"
+    git push origin production # or whatever branch you specified in deploy.rb
+    cap deploy
+
+## Additional Configuration
+
+*Shared Folders and Symlinks*
+
+I wanted to keep this as simple as possible as well. By default, *Deployer* will create folders for storing the production.log in and other necessary stuff. It will properly symlink it from the shared folder to the Rails application. However! You will most likely have some other things you must keep in a shared folder, such as assets or other files. This can be done easily with *Deployer*.
+
+Again, inside of config/deploy.rb
+
+    set :additional_shared_folders,
+      %w(public/assets db)
+
+In this example two paths will be created.
+
+- /var/rails/:appname/shared/public/assets
+- /var/rails/:appname/shared/db
+
+*Deployer* will ensure these are available after every deployment. And will append any folders if you change the values here and re-deploy.
+
+Now, what use are these folders if you do not have the ability to add symlinks from these folders to the application.
+
+    set :additional_shared_symlinks,
+      %w(public/assets db/production.sqlite3)
+  
+In this example two symlinks will be created from the shared_path to the current Rails application release.
+As you can see the first symlink is a "path" symlink, which does not point to a direct file, but rather a folder.
+
+The second symlink will be a link from the shared/db/production.sqlite3 to the current rails applications' db/production.sqlite3 file.
+
+*NOTE*
+
+One important thing to note here is that notice how the symlinks are mirrored to the Rails applications folder structure. This will always be the case. If you have some crazy architecture inside your Rails application: *rails_root/my/awesome/folder/structure/is/very/long* then you MUST create the following folder structure for the shared path: *shared/my/awesome/folder/structure/is/very/long*. This is a convention and it saves a lot of overhead in your configuration file by just defining a path once and using that same path for both the current and shared path.
+
+*Additional (Optional) (Server) Configuration*
+
+Here you can specify that you want to pull/push from/to a git repository that's located on a DIFFERENT server. Leave this commented out or remove it if your git repository resides on the same server as your Rails application. If you choose to store your git repository on a separate server by uncommenting the following line, then you lose the ability to create/reset/destroy/reinitialize it through *Deployer*. This is no big deal though. All you have to do is create the git repository manually on that specific server and then issue the *git remote add origin repository_url* and it will work fine with the rest of *Deployer*.
+
+    set :repository_url, "deployer@example.com:/path/to/repository.git"
+
+And then here is the last bit of server configuration you can specify.
+
+### *Adding Application Specific Deployment Tasks*
+
+Inside the *namespace :deploy do* block you can define your own deployment tasks that are specific to your application.
+
+    ##
+    # Application Specific Deployment Tasks
+    # In here you may specify any application specific and/or other tasks that are not handled by Deployer
+    # These can be invoked by creating a "run_custom_task" method in the "after_deploy" method above
+    namespace :deploy do  
+      desc "Invoke this task manually by running: 'cap deploy:my_custom_task'"
+      task :my_custom_task do
+        # run "some command"
+      end
+  
+      namespace :nested do
+        desc "Invoke this task manually by running: 'cap deploy:nested:my_custom_task'"
+        task :my_custom_task do
+          # system "some command"
+        end
+      end
+    end
+
+Again, very straightforward. Just define your tasks as you normally would with Capistrano.
+Then, to invoke them during each deployment you must add them inside the *after_deploy*, method like so:
+
+    def after_deploy
+      run_custom_task "my_custom_task"
+      run_custom_task "nested:my_custom_task"
+    end
+
+This method will be invoked right before *Deployer* sets permissions on, and restarts the your Rails application. 
+
+
+### Built-in Additional Tasks
+
+*Deployer* has some built-in tasks that are often used by developers.
+
+*Whenever*, To update the crontab on deployment:
+
+    def after_deploy
+      run_custom_task "whenever:update_crontab"
+    end
+
+*Delayed Job*, To start/stop daemons
+
+    def after_deploy
+      run_custom_task "delayed_job:start"
+      run_custom_task "delayed_job:start n=3" # "n" specifies the amount of daemons that should run
+      run_custom_task "delayed_job:stop"
+    end
+
+## Assumptions / Conventions
+
+- Assumes you are using Phusion Passenger
+- Assumes Git Repository will be located on the same server as where the actual application will be deployed. Unless specified otherwise in the deploy.rb file.
+- The config/database.yml will be transferred to the shared/config/database.yml and symlinked to on the initial deployment. You can re-sync it later with *cap deploy:db:sync_yaml*.
+- Assumes you are using Bundler, it no longer supports config/environment.rb's **gem.config** (You can also use Bundler with Rails 2 apps)
+
+## Suggestions, Requests, Idea's?
+
+Tell, Ask, Fork and Help!
+
+## Copyright
+
+Copyright (c) 2010 Michael van Rooijen. See LICENSE for details.

data/lib/deployer/helpers.rb

@@ -1,27 +1,57 @@
-# Creates a tmp directory and writes Apache and NginX configuration files to it
-def create_tmp_file(contents)
-  system 'mkdir tmp'
-  file = File.new("tmp/#{domain}", "w")
-  file << contents
-  file.close
-end
-
+##
 # Alias for initializing custom deployment tasks
 def run_custom_task(task)
   system "cap deploy:#{task}"
 end
 
-# A Helper Method that assists in loading in tasks from the tasks folder
+##
+# Helper Method that assists in loading in tasks from the tasks folder
 def load_tasks(tasks)
   load File.join(File.dirname(__FILE__), '..', 'tasks', "#{tasks}.rb")
 end
 
-# A Method that logs a message
+##
+# Method that logs a message
 def log(message)
   puts "\n\n[Deployer] => #{message}.. \n\n"
 end
 
+##
 # Returns the RAILS_ENV=production string to reduce overhead
 def env
   "RAILS_ENV=production"
+end
+
+##
+# Returns the path to the 'rake' executable
+def rake_path
+  return @rake_path if @rake_path
+  Net::SSH.start(ip, user) do |ssh|
+    @rake_path = ssh.exec!("which rake").chomp || "rake"
+  end
+  @rake_path
+end
+
+##
+# Returns the path to Bundler's 'bundle' executable
+def bundle_path
+  return @bundle_path if @bundle_path
+  Net::SSH.start(ip, user) do |ssh|
+    @bundle_path = ssh.exec!("which bundle").chomp || "bundle"
+  end
+  @bundle_path  
+end
+
+##
+# Returns true or false, depending on whether the bundle is satisfied (dependencies are installed)
+def bundle_satisfied?
+  return @bundle_satisfied if @bundle_satisfied
+  Net::SSH.start(ip, user) do |ssh|
+    if ssh.exec!("cd #{current_path}; #{bundle_path} check") =~ /The Gemfile's dependencies are satisfied/
+      @bundle_satisfied = true
+    else
+      @bundle_satisfied = false
+    end
+  end
+  @bundle_satisfied
 end

data/lib/deployer/initializer.rb

@@ -1,5 +1,5 @@
-# Returns a path that can be loaded by the "load" method
-# inside the Capfile
+##
+# Returns a path that can be loaded by the "load" method inside the Capfile
 def deployer
   File.join(File.dirname(__FILE__), '..', 'deployer.rb')
 end

data/lib/deployer.rb

@@ -1,36 +1,34 @@
+##
 # Load Deployer Helpers
 require File.join(File.dirname(__FILE__), 'deployer', 'helpers')
 
-# This configuration is *conventional*
+##
+# This Configuration Is *Conventional*
 set   :application,         ip
-set   :deploy_to,           "/var/rails/#{domain}"
-set   :repository_path,     "/var/git/#{domain}.git"
+set   :deploy_to,           "/var/apps/#{appname}"
+set   :repository_path,     "/var/git/#{appname}.git"
 set   :repository,          "#{user}@#{application}:#{repository_path}"
 set   :repository,          repository_url if respond_to?(:repository_url)
 
-set   :scm,                 "git"
-set   :use_sudo,            true
+set   :scm,                 'git'
+set   :use_sudo,            false
 role  :web,                 application
 role  :app,                 application
 role  :db,                  application
 default_run_options[:pty] = true
 
+##
 # Default Configuration
-set :remote,                          "origin"                          unless respond_to?(:remote)
-set :branch,                          "master"                          unless respond_to?(:branch)
-set :apache_initialize_utility_path,  "/etc/init.d/apache2"             unless respond_to?(:apache_initialize_utility_path)
-set :apache_sites_available_path,     "/etc/apache2/sites-available"    unless respond_to?(:apache_sites_available_path)
-set :nginx_initialize_utility_path,   "/etc/init.d/nginx"               unless respond_to?(:nginx_initialize_utility_path)
-set :nginx_sites_enabled_path,        "/opt/nginx/conf/sites-enabled"   unless respond_to?(:nginx_sites_enabled_path)
+set :remote, 'origin' unless respond_to?(:remote)
+set :branch, 'master' unless respond_to?(:branch)
 
+##
 # Load Deployment Tasks
-load_tasks("global")
-load_tasks("passenger")
-load_tasks("apache")
-load_tasks("nginx")
-load_tasks("plugin")
-load_tasks("db")
-load_tasks("gems")
-load_tasks("repository")
-load_tasks("environment")
-load_tasks("commands")
+load_tasks('global')
+load_tasks('passenger')
+load_tasks('plugin')
+load_tasks('db')
+load_tasks('gems')
+load_tasks('repository')
+load_tasks('environment')
+load_tasks('commands')

data/lib/tasks/commands.rb

@@ -3,13 +3,13 @@ namespace :deploy do
   
     desc "Run a command from the Rails Root on the remote server. Specify command='my_command'."
     task :rails_root do
-      log "Executing \"#{ENV['command']}\" from the Rails Root on the server."
+      log "Executing \"#{ENV['command']}\" from the Application's root path."
       run "cd #{current_path}; #{ENV['command']}"
     end
    
     desc "Run a command on the remote server. Specify command='my_command'."
     task :default do
-      log "Executing \"#{ENV['command']}\" on the server."
+      log "Executing \"#{ENV['command']}\"."
       run "#{ENV['command']}"
     end
      

data/lib/tasks/db.rb

@@ -3,7 +3,7 @@ namespace :deploy do
     
     desc "Syncs the database.yml file from the local machine to the remote machine"
     task :sync_yaml do
-     log "Syncing database yaml to the production server"
+     log "Syncing local database.yml (config/database.yml) to the shared folder (#{appname}/shared/config/database.yml)"
      unless File.exist?("config/database.yml")
        puts "There is no config/database.yml.\n "
        exit
@@ -11,40 +11,38 @@ namespace :deploy do
      system "rsync -vr --exclude='.DS_Store' config/database.yml #{user}@#{application}:#{shared_path}/config/"
     end
 
-    desc "Create Production Database"
+    desc "Create the database"
     task :create do
-     log "Creating the Production Database"
-     run "cd #{current_path}; rake db:create #{env}"
+      log "Creating the database"
+      run "cd #{current_path}; #{rake_path} db:create #{env}"
     end
     
     namespace :migrate do
       
-      desc "Migrate Production Database"
+      desc "Migrate the database"
       task :default do
-       log "Migrating the Production Database"
-       run "cd #{current_path}; rake db:migrate #{env}"
+       log "Migrating the database"
+       run "cd #{current_path}; #{rake_path} db:migrate #{env}"
       end
 
-      desc "Resets the Production Database"
+      desc "Reset the database"
       task :reset do
-       log "Resetting the Production Database"
-       run "cd #{current_path}; rake db:migrate:reset #{env}"
-       system "cap deploy:set_permissions"
+       log "Resetting the database"
+       run "cd #{current_path}; #{rake_path} db:migrate:reset #{env}"
       end
 
     end
       
-    desc "Destroys Production Database"
+    desc "Drop the database"
     task :drop do
-     log "Destroying the Production Database"
-     run "cd #{current_path}; rake db:drop #{env}"
+     log "Dropping the database"
+     run "cd #{current_path}; #{rake_path} db:drop #{env}"
     end
 
-    desc "Populates the Production Database"
+    desc "Populate the database"
     task :seed do
-     log "Populating the Production Database"
-     run "cd #{current_path}; rake db:seed #{env}"
-     system "cap deploy:set_permissions"
+     log "Seeding the database"
+     run "cd #{current_path}; #{rake_path} db:seed #{env}"
     end
     
   end

data/lib/tasks/gems.rb

@@ -1,14 +1,18 @@
 namespace :deploy do
   namespace :gems do
     
-    desc "Installs any 'not-yet-installed' gems on the production server or a single gem when the gem= is specified."
+    desc "Installs dependencies for application, or a single gem when the gem= is specified."
     task :install do
       if ENV['gem']
         log "Installing #{ENV['gem']}"
         run "gem install #{ENV['gem']}"
       else
         log "Installing gem dependencies"
-        run "cd #{current_path}; rake deployer_gems:install #{env}"
+        if bundle_satisfied? and ENV['force'] != "true"
+          puts "The Gemfile's dependencies are satisfied"
+        else
+          run "cd #{current_path}; #{bundle_path} install"
+        end
       end
     end
     

data/lib/tasks/global.rb

@@ -7,51 +7,35 @@ namespace :deploy do
     system "cap deploy:gems:install"
     system "cap deploy:db:create"
     system "cap deploy:db:migrate"
-    after_deploy if respond_to?(:after_deploy)    
-    system "cap deploy:set_permissions"
+    after_deploy if respond_to?(:after_deploy)
     system "cap deploy:passenger:restart"
   end
 
-  desc "Executes the initial procedures for deploying a Ruby on Rails Application."
+  desc "Executes the initial procedures for deploying a Ruby on Rails application."
   task :initial do
     system "cap deploy:setup"
     system "cap deploy:setup_shared_path"
     system "cap deploy:db:sync_yaml"
-    system "cap deploy:sync_tasks"
-    system "cap deploy"
-  end
-  
-  desc "Sets permissions for Rails Application"
-  task :set_permissions do
-    log "Setting Permissions"
-    run "chown -R www-data:www-data #{deploy_to}"
-  end
-  
-  desc "Creates symbolic links from shared folder"
-  task :setup_symlinks do
-    log "Setting up Symbolic Links"
-    run "mkdir -p #{File.join(current_path, 'lib', 'tasks')}"
-    shared_symlinks = %w(config/database.yml lib/tasks/deployer.rake)
-    shared_symlinks += additional_shared_symlinks if respond_to?(:additional_shared_symlinks)
-    shared_symlinks.each do |symlink|
-      run "ln -nfs #{File.join(shared_path, symlink)} #{File.join(current_path, symlink)}"
-    end
   end
   
   desc "Sets up the shared path"
   task :setup_shared_path do
-    log "Setting up the shared path"
+    log "Setting up the shared folders"
     shared_folders = %w(config lib/tasks)
     shared_folders += additional_shared_folders if respond_to?(:additional_shared_folders)
     shared_folders.each do |folder|
       run "mkdir -p #{shared_path}/#{folder}"
     end
   end
-
-  desc "Syncs the rake tasks for installing gems."
-  task :sync_tasks do
-    log "Adding Deployer Rake tasks to shared path."
-    system "rsync -vr --exclude='.DS_Store' #{File.join(File.dirname(__FILE__), '..', 'deployer', 'tasks', 'deployer.rake')} #{user}@#{application}:#{File.join(shared_path, 'lib', 'tasks')}"
+  
+  desc "Creates symbolic links from the application to the shared folders"
+  task :setup_symlinks do
+    log "Creating symbolic links from the application to the shared folders"
+    shared_symlinks = %w(config/database.yml)
+    shared_symlinks += additional_shared_symlinks if respond_to?(:additional_shared_symlinks)
+    shared_symlinks.each do |symlink|
+      run "ln -nfs #{File.join(shared_path, symlink)} #{File.join(current_path, symlink)}"
+    end
   end
 
 end

data/lib/tasks/passenger.rb

@@ -3,7 +3,7 @@ namespace :deploy do
     
     desc "Restarts Passenger"
     task :restart do
-      log "Restarting Passenger"
+      log "Restarting #{appname}"
       run "touch #{current_path}/tmp/restart.txt"
     end
 

data/lib/tasks/plugin.rb

@@ -1,23 +1,23 @@
 namespace :deploy do
   namespace :whenever do
     
-    desc "Update the crontab file for the Whenever Gem."
+    desc "Update the crontab file for the Whenever gem."
     task :update_crontab, :roles => :db do
-      log "Updating the Crontab"
-      run "cd #{release_path} && whenever --update-crontab #{domain}"
+      log "Updating the crontab"
+      run "cd #{release_path} && whenever --update-crontab #{appname}"
     end    
   end
 
   namespace :delayed_job do
-    desc "Starts the Delayed Job Daemon(s)."
+    desc "Starts the Delayed Job daemon(s)."
     task :start do
-      log "Starting #{(ENV['n'] + ' ') if ENV['n']}Delayed Job Daemon(s)"
+      log "Starting #{(ENV['n'] + ' ') if ENV['n']}Delayed Job daemon(s)"
       run "#{env} #{current_path}/script/delayed_job #{"-n #{ENV['n']} " if ENV['n']}start"
     end
     
-    desc "Stops the Delayed Job Daemon(s)."
+    desc "Stops the Delayed Job daemon(s)."
     task :stop do
-      log "Stopping Delayed Job Daemon(s)"
+      log "Stopping Delayed Job daemon(s)"
       run "#{env} #{current_path}/script/delayed_job stop"
     end
   end