• V2CapistranoDeployment

Capistrano Deployment

V2Master - V2Deployment

• Contents

  1. Capistrano Deployment
  2. Introduction
  3. V2 Deployment Git Tree
  4. Capistrano Customization
     1. Capistrano Custom Command Line Parameters
     2. Capistrano Deployment Variable
     3. Capistrano Custom Tasks
  5. VM Setup and Provisioning
  6. Application Deployment
     1. Specific Instance Deployment
     2. Generic Instance Deployment
  7. Example Deployments
     1. Example: Specific Development Instance
        1. Example Command Lines
     2. Example: Specific Production Instance
        1. Example Command Lines
     3. Example: Generic Production Instance
        1. Example Command Lines

Introduction

This page describes how Capistrano is used for:

1. The V2 deployment git tree used to store and manage V2 and MAPS deployment configurations
2. Capistrano customization
3. VM setup and provisioning
4. Application deployment
5. Example deployments

V2 Deployment Git Tree

Capistrano Customization

Capistrano Custom Command Line Parameters

• Parameter Name	Example Value	Description
  app	maps	MAPS application
  	v2p0	V2 application
  	vagrant	Virtual machine setup/provisioning
  site	proto	Prototype instance of V2 and MAPS
  	v2	V2 virtual machine for vagrant provision
  instance	zg-3.softxs.ch	Example MAPS instance: v2.softxs.ch/maps
  	zg-3.softxs.ch	Example v2p0 instance: v2.softxs.ch/v2p0
  	zg-3.softxs.ch-tn	Example v2p0 instance: v2.softxs.ch/v2p0-tn
  	vor.softxs.ch-4010	Example v2p0 instance: localhost:4010 on AH laptop
  	generic	Generic instance, must set vh and vm
  vh	1	Virtual host specified
  vm	192.168.4.9	Internal IP address of virtual host

Capistrano Deployment Variable

• Capistrano Variable Name	Typical Value	Description
  Source Control Checkout
  scm_user	alan	User for git checkout on git server
  scm	git	Source control system
  repository	alan@git.softxs.ch:/home/git/gitroot/v2p0.git	Git repository
  branch	master	Branch to install
  Target Machine
  deploy_to	/v01/local/www/rails/v2p0-app	Deploy path on target server
  servpath	v2.softxs.ch	server part of the path used in common directories by deploy:setup_ext_dirs
  relpath	v2p0-jk5	relative part of the path used in common directories by deploy:setup_ext_dirs
  rails_env	production	Rails environment. Typically only production
  user	v2	User on target server
  group	www	Group on target server
  current_path	/v01/local/www/rails/v2p0-app/current	Current path on target server
  release_path	/v01/local/www/rails/v2p0-app/releases/20130717103024	Release path on target server
  current_release	/v01/local/www/rails/v2p0-app/releases/20130613060901	Currently running release (before installation)
  Vagrant Target Machine Applicable only if app=vagrant, and site=v2
  user	vagrant	Vagrant user on virtual host server
  vh_fqdn	vh01.softxs.ch	Virtual host fully-qualified hostname
  vh_home	/home/vms/vm0409	Path to VM on virtual host server
  vm_box	lucid64_v2base2	Name of virtual box (instance) to install
  vm_name	vm0409	Virtual machine name
  Vagrant Generic Parameters Applicable only if instance=generic
  vh_name	vh01	Virtual host hostname
  vh_fqdn	vh01.softxs.ch	Virtual host fully-qualified hostname
  vm_ip	192,168.4.9	Internal IP address of VM
  vm_ssh_port	4009	Port number for SSH acces
  vm_name	vm0409	VM hostname
  vm_int_name	vm0409.vh01	VM internal hostname
  vm_int_fqdn	vm0409.vh01.softxs.ch	VM fully qualified internal hostname
  vm_ext_name	vm0409vh01	VM public hostname
  vm_ext_fqdn	vm0409vh01.softxs.ch	VM fully-qualified public hostname

Capistrano Custom Tasks

Capistrano has a number of pre-defined default tasks, which are defined in:

• {gempath}/gems/ruby-{ruby_version}/gems/capistrano-{capistrano_version}/lib/capistrano/recipes/deploy.rb

If yuo need to understand what a particular Capistrano task does, then look in this file.

The list of all Capistrano tasks, including both the pre-defined default tasks and the custom tasks, with descriptions, can displayed with the command cap -T.

• cap -T
  cap delayed_job:restart                   # Restart the delayed_job process
  cap delayed_job:start                     # Start the delayed_job process
  cap delayed_job:stop                      # Stop the delayed_job process
  cap deploy                                # Deploys your project.
  cap deploy:assets:clean                   # Run the asset clean rake task.
  ...
  cap deploy:upload                         # Copy files to the currently deployed version.
  cap deploy:web:disable                    # Present a maintenance page to visitors.
  cap deploy:web:enable                     # Makes the application web-accessible again.
  cap invoke                                # Invoke a single command on the remote servers.
  cap mysql:backup                          # * Make a database backup to the app share/backup
  cap setup_app_symlink                     # * Setup application symlink, automatically called aft...
  cap setup_env                             # * Setup the application, site and instance settings f...
  cap shell                                 # Begin an interactive Capistrano session.
  cap show_env                              # * Display installation settings
  cap v2:delayed_job:start                  # * V2 delayed_job start
  cap v2:delayed_job:stop                   # * V2 delayed_job stop
  cap vagrant:setup                         # * Setup Vagrant VM (create VM home dir and install Va...
  cap vagrant:start                         # * Start Vagrant VM (vagrant up)
  cap vagrant:status                        # * Display status of Vagrant VM
  cap vagrant:stop                          # * Stop Vagrant VM (vagrant halt)

Notes:

1. You must be in v2deploy directory to be able to display the task list

2. By our own convention, the custom V2 deployment tasks are marked with a * at start of the task description.

The following is a list, with descriptions, of the V2 custom tasks:

• Task Name	Description
  Top-Level Tasks
  setup_env	Setup the application, site and instance settings for the installation
  show_env	Display installation settings
  setup_app_symlink	Setup application symlink, automatically called after deploy:setup
  upload_database_yml	Install database.yml file
  Deployment Tasks
  deploy:setup_ext_dirs	Setup external dirs: /data, /backup, symlink shared/var --> /data/.../var, shared/bundle --> ../bundle, call manually after deploy:setup
  deploy:populate	Pupulate application database (rake db:populate)
  deploy:provision	Provision VM for application.
  deploy:restart	Restart application (by touching tmp/restart.txt)
  deploy:seed_fu	Seed the application database (rake db:seed_fu)
  deploy:seed_fu_without_access_control	Seed V2 application database (rake db:seed_fu_without_access_control...
  VM Provisioning Tasks
  vagrant:setup	Setup Vagrant VM (create VM home dir and install Vagrant file)
  vagrant:start	Start Vagrant VM (vagrant up)
  vagrant:status	Display status of Vagrant VM
  vagrant:stop	Stop Vagrant VM (vagrant halt)

VM Setup and Provisioning

• to be completed

Application Deployment

Specific Instance Deployment

Generic Instance Deployment

Example Deployments

Example: Specific Development Instance

1. Install git tree by hand
2. Using webbrick as web server
3. Use Capistrano to install site and instance specific files
4. Run bundle and rake tasks by hand

Example Command Lines

Example deployment on MacOS laptop:

• cd ~/rails/v2deploy    # Where v2deploy.git is checked out
  cap -s app=v2p0 -s site=proto -s instance=vor.softxs.ch-3010 deploy:site_files deploy:instance_files
  
  cd ~/rails/v2p0        # Where v2p0.git is checked out
  bundle install
  ..etc.
  
  rails server -p 3010

Note that changes to the site and instance files, typically database.yml and settings.local.yml must be copied by hand back into the appropriate place in the v2deploy tree and committed.

Example: Specific Production Instance

1. Install git tree by hand
2. Using pre-configured APache virtual host as web server
3. Capistrano to install everything
   1. Setup of target environment: Mix of hand and automated steps
   2. Local git checkout and installation on server
   3. RRun bindle and rake tasks

Example Command Lines

1. Install MAPS on zg-3.softxs.ch server:

   • cap -s app=maps -s site=proto -s instance=zg-3.softxs.ch \
       deploy:setup deploy deploy:migrate deploy:start

2. Install V2 on zg-3.softxs.ch server:

   • cap -s app=v2p0 -s site=proto -s instance=zg-3.softxs.ch \
       deploy:setup deploy deploy:create deploy:schema_load deploy:seed_fu_without_access_control deploy:start

3. Install V2 on a virtual machine v2 on zg-3.softxs.ch server:

   • cap -s app=v2p0 -s site=proto -s instance=zg-3.softxs.ch \
       deploy:setup deploy:setup_ext_dirs deploy deploy:create deploy:schema_load deploy:seed_fu_without_access_control deploy:start

Example: Generic Production Instance

1. Creating VM on virtual host
2. Provisioning VM on virtual host
   1. Including creation of Apache virtual host
3. Application installation

Note that DMS (re-)configuration is not included, this must be prepared separately, typically using Puppet. See:

• V2PuppetDeployment

Example Command Lines

1. Setup a new VM and install V2 on it
   • The virtual host for the MV is vh01.softxs.ch
   • The new VM will have an internal IP address of 192.168.4.9
   • The virtual hostname for accessing the application will be vm0401vh01.softxs.ch, which must be defined in advance in DNS

     cap -v -s app=vagrant -s site=v2 -s instance=generic -s vh=1 -s vm=192.168.4.9 vagrant:setup vagrant:start
     cap -v -s app=v2p0 -s site=proto -s instance=generic -s vh=1 -s vm=192.168.4.9 deploy:provision
     cap -v -s app=v2p0 -s site=proto -s instance=generic -s vh=1 -s vm=192.168.4.9 \
       deploy:setup deploy bundle:install deploy:migrate deploy:populate deploy:start