= Capistrano Deployment = [[V2Master]] - [[V2Deployment]] <> = Introduction = This page describes how [[https://github.com/capistrano/capistrano|Capistrano]] is used for: 1. The V2 deployment git tree used to store and manage V2 and MAPS deployment configurations 1. Capistrano customization 1. VM setup and provisioning 1. Application deployment 1. Example deployments = V2 Deployment Git Tree = = Capistrano Customization = == Capistrano Custom Command Line Parameters == || '''Parameter Name''' || '''Example Value''' || '''Description''' || ||<|3> app || maps || MAPS application || || v2p0 || V2 application || || vagrant || Virtual machine setup/provisioning || ||<|2> site || proto || Prototype instance of V2 and MAPS || || v2 || V2 virtual machine for vagrant provision || ||<|5> 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'' || ||<|1> vh || 1 || Virtual host specified || ||<|1> vm || 192.168.4.9 || Internal IP address of virtual host || == Capistrano Deployment Variable == || '''Capistrano Variable Name''' || '''Typical Value''' || '''Description''' || ||<-3> '''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 || ||<-3> '''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) || ||<-3> '''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 || ||<-3> '''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 1. 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''' || ||<-2> '''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 || ||<-2> '''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... || ||<-2> '''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 1. Using webbrick as web server 1. Use Capistrano to install site and instance specific files 1. 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 1. Using pre-configured APache virtual host as web server 1. Capistrano to install everything 1. Setup of target environment: Mix of hand and automated steps 1. Local git checkout and installation on server 1. 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 }}} 1. 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 }}} 1. 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 1. Provisioning VM on virtual host 1. Including creation of Apache virtual host 1. 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 }}}