Capistrano and php

Hello. Today I would like to once again talk about the remarkable Capistrano deployer.

Let me remind you that Capistrano is an Open Source tool for running scripts on multiple servers, which is mainly used for web applications. It allows you to automate the process of deploying a new version on one or more web servers and includes support for tasks such as changing the database.

Capistrano is written in Ruby and is a “module” (or component, I don’t know which is better) of the Ruby on Rails framework.
')
This topic for the most part is a translation of the tutorial from the project page to github, with some additions, changes and abbreviations specific to php (or for “non-RoR”). It will not address issues of working with multiple servers and databases, this is just a small tutorial for beginners.

So, let's say on our local computer in the / path / deploy / from package there is an application written in the php language. This application has a git repository located at example.net/project.git with the actual code. We also have a hosting at example.com with ssh access and the / path / deploy / to folder where we are going to upload our files. We do not want to constantly mess with the ftp client and decided to spend a few hours in order to understand the capistrano Deployer. Let's get started.

Installation

Let's start with the installation. open the console and enter:

$ sudo apt-get install ruby rubygems $ sudo gem install capistrano 

Since the RoR configuration files are in the config folder, capistrano assumes that we have it. If not, then you need to create it:

  $ mkdir /path/deploy/from/config 

If the directory in which you create the config directory is also the root directory of the server, then do not forget to put in it an .htaccess file for apache, which prevents viewing of files in this directory, or in the configuration of other web servers to deny access to this directory.

Capacity

The first thing we need to do after installing capistrano is “capify-nuth” our application. Capification is the process of configuring capistrano to deploy an application. It is quite simple: make sure that you are in the root directory of your project and enter:

  $ cd /path/deploy/from $ capify . 

This command will create two files:

Capfile - the main file that capistrano needs. Just as “make” uses “Makefile”, and “rake” - “rakefile”, Capistrano by default searches for and loads “Capfile”. Initially generated by Capfile is very simple: all it does is load “config / deploy.rb” ...

config/deploy.rb - file which contains the “settings” of the application.
Generally speaking we need to leave Capfile alone and come to grips with the file config / deploy.rb. Initially, it will look like this:

  set :application, "set your application name here" set :repository, "set your repository location here" set :scm, :subversion # Or: `accurev`, `bzr`, `vcs`, `darcs`, `git`, `mercurial`, `perforce`, `subversion` or `none` role :web, "your web-server here" # Your HTTP server, Apache/etc role :app, "your app-server here" # This may be the same as your `Web` server role :db, "your primary db-server here", :primary => true # This is where Rails migrations will run role :db, "your slave db-server here" # If you are using Passenger mod_rails uncomment this: # if you're still using the script/reapear helper you will need # these http://github.com/rails/irs_process_scripts # 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 

This configuration does not suit us, so we will rewrite it.

Configuration

First, the application needs to be given a name. Let's call it "my php application":

  set :application, "my php application" 

Then you need to specify the repository where our code is located. This repository should be accessible from both your local machine and from the hosting where you want to deploy the project. We set our repository:

  set :repository, "ssh://git@example.net/project.git" 

If the url for accessing the repository from the local machine and from the server is different (for example, outside ssh has a different port), you need to specify both addresses:

  set :repository, "ssh://git@example.com:22100/project.git" set :local_repository, "ssh://git@example:project.git" 

Since we are using a version control system different from Subversion, which is assigned by default, you need to enter the following line:

  set :scm, :git 

Now you need to specify Capistrano in which folder on the server we want to deploy the project. To understand what this means, you need to consider the directory structure that Capistrano uses to deploy applications.

Capistrano directory structure

A project successfully deployed with Capistrano will have a structure similar to the one below (where [deploy_to] is the directory where we want to deploy the project):

  [deploy_to] [deploy_to]/releases [deploy_to]/releases/20080819001122 [deploy_to]/releases/... [deploy_to]/shared [deploy_to]/shared/log [deploy_to]/shared/pids [deploy_to]/shared/system [deploy_to]/current -> [deploy_to]/releases/20100819001122 

Every time you deploy a project in the “releases” folder, a new directory will be created, to which its latest version will be copied. After that, the symbolic link “current” will be updated and will point to the new directory. If the structure of your application is similar to the structure of an application in RoR or another application where the root directory of the project and the web directory are different, you need to make sure that the server is configured for this directory (in RoR it is [deploy_to] / current / public).

Back to configuration

So we need to specify where on the server we want to deploy the application. By default, this is the folder "/ u / apps / # {application}" (where # {application} is the name we indicated above in the variable ": application"). Since our directory is different from the default directory, we explicitly specify it:

  set :deploy_to "/path/deploy/to" 

Now you need to specify where our servers are located. Generally speaking, Capistrano by default uses three roles to deploy Rails applications: web, app, and db. A detailed description of these roles can be found in the original article. Since we have only one server and we do not need the functionality of the roles, you can use the following syntax:

  server "example.com" 

Additional settings

Now look at some additional variables that may be useful to you.

•  set :user, "foo" 

  Specifies the username for ssh or ftp access if you connect to the server under a name other than the name under which you are logged into your local computer.
  

•  set :password, "password" 

  Sets the password for connecting to the server. Not recommended.
  

•  set :scm_username, "foo" 

  Specifies the user name for accessing the repository, if you connect to it under a name other than the name under which you are logged on to the local computer. Not all vcs support this option. If your version control system does not support, then you must specify this name in the parameter ": repository" as it is done above.
  

•  set :use_sudo, false 

  Assigned by default. If you want to give Capistrano sudo access to perform any operations, set true
  

•  set :via, "scp" 

  Sets the protocol by which data will be copied.
  

•  set :branch, "master" 

  Specifies the project branch from which the code will be taken.
  

•  set :deploy_via, :remote_cache 

  Saves the latest version of the cache on the server and with the new deploy-e download only updates. You will probably want to set this parameter.
  

Capistrano Commands

Once we have written our recipe, you can ask Capistrano a few questions:

•  $ cap -h 

  Displays a list of possible options.
  

•  $ cap -H 

  Displays a list of all options with a detailed description of each of them.
  

•  $ cap -T 

  Displays a list of all tasks (or tasks) with a brief description of each of them.
  

•  $ cap -e deploy:web_disable 

  Show detailed information about a specific task.
  

Setup

Let's try to use kapistrano to interact with the server. First we need to create a basic directory structure:

  $ cap deploy:setup 

When you run this command, the capistrano connects to the server and executes a series of “mkdir” commands. In advance, make sure that everything is in order with the access rights to the directory in which you are deploying the project.

Dependency Check

Now that we have a skeleton, we can ask the capistrano if we have everything we need to continue expanding the project:

  $ cap deploy:check 

Capistrano will check the local and remote server for necessary items. If something is missing, you will receive an error message, for example, that you do not have rights to any operation, that git is not installed on the server, etc.

Sending code to the server

Now we will not perform a full-fledged deployment, but we will just try to upload the code to the server to make sure that everything is in order at this stage:

  $ cap deploy:update 

This command downloads the code from the repository to the server and updates the “current” symlink.

Deploy

Finally, we got close to the deployment. In reality, the deploy command is just a wrapper, on several other commands that simply executes them sequentially. How this happens can be viewed in the following diagram:



Since the deploy: update and deploy: finalize_update commands are specific to applications written in ruby ​​on rails, we need to redefine them. In addition to these two commands, I recommend overriding the deploy: start and deploy: stop commands, since they are also sharpened for RoR and can lead to an error if they are started (in fact, there are other specific commands, but we override only the most important ones):

  namespace :deploy do task :start do end task :stop do end task :restart do end task :finalize_update do end end 

In principle, now the deploy command is no different from the deploy: update command, but you can change this by writing actions specific to your application in the required tasks.

Now the Deployer is ready to go. For those who do not have the described capabilities, I recommend that you familiarize yourself with the DSL Documentation section on the project’s wiki page and carefully read the output of the “cap-e” command for each standard task. After reading them you can easily write constructions such as:

  after "deploy", "deploy:cleanup" 

If you add such a line to the recipe, then after each deployment, the directory / path / deploy / to / releases will be automatically cleaned (by default, all releases except the last 5 are removed).

Multistage

In our development, we also use the capistrano-ext extension, which allows us to do the so-called multistage. Suppose you have a test and a working server. You can write a separate config for each of them and perform deploy only for the server you need.
To install an extension, type in the command line:

  $ gem install capistrano-ext 

Next in the folder / path / deploy / from / config / create a new directory:

  $ mkdir /path/deploy/from/config/deploy 

and put our recipes in it: for example production.rb and staging.rb. All we need for the configuration is to write two lines to the /path/deploy/from/config/deploy.rb file:

  set :stages, %w(staging production) require 'capistrano/ext/multistage' 

Now you can execute deploy with the commands “cap production deploy” and “cap staging deploy”. If you need another config, just put it in the deploy directory and add its name to the variable :stages :

  set :stages, %w(staging production develop) 

If you try to simply execute the “cap deploy” command, capistrano will warn you that you need to specify a recipe for which you need to perform warmth and interrupt the work. In order to use any recipe by default, you can define the variable "default_stage":

  set :stages, %w(staging production develop) set :default_stage, "develop" require 'capistrano/ext/multistage' 

Now the command “cap deploy” will be equivalent to the command “cap develop deploy”.

That's all, thank you for your attention.

PS: Calling the publication a translation did not turn the language, because here less than half of the tutorial. A lot of things are taken from other articles and from personal experience.

original tutorial
article about multistage
help.github.com/capistrano