Capistrano

Objective

This guide explains how to use Capistrano on Ruk-Com Cloud PaaS, with ordered procedures and practical verification points.

Before you begin

• Sign in with an account permitted to manage the relevant environment.
• Confirm the target environment, region and resources before saving changes.
• Create a backup or rollback plan before changing a production system.

Capistrano is an open-source tool for running scripts on remote servers, typically used for deploying apps over SSH connections. Capistrano is written in Ruby. It is a component of the Ruby on Rails framework, so it is widely used for deploying Ruby apps. However, it is easily compatible with other programming languages such as PHP.

In this article, let's look at how to deploy a php application remotely via the Capistrano tool. In the first step you will need:

• Create a PHP environment with Apache application server.
• Creating an SSH public keyandAdd to Ruk-Com CloudDashboard
• GIT repository to hold the php application you want to deploy (for now the Capistrano 3 tool only supports the GIT VCS type)
• Copy this project to your machine.

Note:The commands below should be executed on your machine the same way you used them during SSH key pair generation to avoid authorization/connection errors.

Installing Capistrano

1. To use Capistrano, you need to install Ruby on your computer by running this command:

apt-get install ruby rubygems

2. Then install the Capistrano tool by entering the following command:

gem install capistrano

3. Make sure you have a config folder in your local directory with the project. (This is the default folder where Ruby on Rails is configured.) If you don't have one, create this folder:

mkdir {path_to_your_project}/config

Capify your application

After installation, you need to capify your application, i.e. configure Capistrano for deploying the app by going to the root folder of your php project and executing this command:

cap install

This will create new files and directories in your project:

• Capfileis the main Capistrano file that takes care of the configuration and globs required for custom jobs.
• config/deploy/Folder with two files (staging.rbandproduction.rb) for environment specific deployment settings
• config/deploy.rbRuby script with application configuration and Capistrano instructions
• lib/capistrano/tasks/Folder for your custom tasks

Tips:You can try using capistrano-jelastic gem maintained by gerado-navarro to automatically deploy Relis apps to PaaS & IaaS

Set customizations

1. Go to the config/deploy.rb file. and configure it according to your settings. Initially it will look like this format:

# config valid only for Capistrano 3.1
    lock '3.2.1'

    set :application, 'my_app_name'
    set :repo_url, '[email protected]:me/my_repo.git'

    # Default branch is :master
    # ask :branch, proc { `git rev-parse --abbrev-ref HEAD`.chomp }.call

    # Default deploy_to directory is /var/www/my_app
    # set :deploy_to, '/var/www/my_app'

    # Default value for :scm is :git
    # set :scm, :git

    # Default value for :format is :pretty
    # set :format, :pretty

    # Default value for :log_level is :debug
    # set :log_level, :debug

    # Default value for :pty is false
    # set :pty, true

    # Default value for :linked_files is []
    # set :linked_files, %w{config/database.yml}

    # Default value for linked_dirs is []
    # set :linked_dirs, %w{bin log tmp/pids tmp/cache tmp/sockets vendor/bundle public/system}

    # Default value for default_env is {}
    # set :default_env, { path: "/opt/ruby/bin:$PATH" }

    # Default value for keep_releases is 5
    # set :keep_releases, 5

    namespace :deploy do

      desc 'Restart application'
      task :restart do
        on roles(:app), in: :sequence, wait: 5 do
          # Your restart mechanism here, for example:
          # execute :touch, release_path.join('tmp/restart.txt')
        end
      end

      after :publishing, :restart

      after :restart, :clear_cache do
        on roles(:web), in: :groups, limit: 3, wait: 10 do
          # Here we can do anything such as:
          # within release_path do
          #   execute :rake, 'cache:clear'
          # end
        end
      end

    end

Edit the following string:

• Enter the name of your application.

set :application, "my_app_name"

• Specify the URL to the VSC repository with PHP application code.

set :repo_url, "[email protected]:me/my_repo.git"

Note:You must attach the SSH public key to your GIT account (the same one you added to the dashboard) or you will get "Permission denied"; An error occurred while attempting to deploy your application.

You can use the linkhttps:The following types:
set :repo_url, "https://example.net/GIT_user_name/repo_name.git"

In this case no authentication is required and you can specify the URL to the PHP open-source repository where you want to deploy.

• Uncomment the following line and specify the directory where the application you will deploy (this is the default for PHP app servers):

# set :deploy_to, '/var/www/webroot'

• Uncomment the following lines.

set :scm, :git
set :format, :pretty
set :pty, true

• Delete strings with code at the end of the file. (starting from the commandnamespace :deploy do) and paste the following line in its place:

namespace :deploy do
        desc 'Restart Apache'
        task :apache do
            on roles(:app) do
                execute :sudo, "service httpd restart"
            end
        end

        desc 'Creating symlink'
        task :symlink do
            on roles(:app) do
                execute :rm, "-rf /var/www/webroot/ROOT"
                execute :ln, "-s /var/www/webroot/current /var/www/webroot/ROOT"
            end
        end

        desc 'Restart Apache and create symlink'
        task :restart
        before :restart, :symlink
        before :restart, :apache

    end

    after 'deploy:publishing', 'deploy:restart'

You can configure additional values in this file (such as specifying repository branches or additional file/folder links).

Press the buttonSaveto save changes

2. Then go to fileconfig/deploy/staging.rbThe default content is:

# Simple Role Syntax
    # ==================
    # Supports bulk-adding hosts to roles, the primary server in each group
    # is considered to be the first unless any hosts have the primary
    # property set.  Don't declare `role :all`, it's a meta role.

    role :app, %w{[email protected]}
    role :web, %w{[email protected]}
    role :db,  %w{[email protected]}

    # Extended Server Syntax
    # ======================
    # This can be used to drop a more detailed server definition into the
    # server list. The second argument is a, or duck-types, Hash and is
    # used to set extended properties on the server.

    server 'example.com', user: 'deploy', roles: %w{web app}, my_property: :my_value

    # Custom SSH Options
    # ==================
    # You may pass any option but keep in mind that net/ssh understands a
    # limited set of options, consult[net/ssh documentation](http://net-ssh.github.io/net-ssh/classes/Net/SSH.html#method-c-start).
    #
    # Global options
    # --------------
    #  set :ssh_options, {
    #    keys: %w(/home/rlisowski/.ssh/id_rsa),
    #    forward_agent: false,
    #    auth_methods: %w(password)
    #  }
    #
    # And/or per server (overrides global)
    # ------------------------------------
    # server 'example.com',
    #   user: 'user_name',
    #   roles: %w{web app},
    #   ssh_options: {
    #     user: 'user_name', # overrides user setting above
    #     keys: %w(/home/user_name/.ssh/id_rsa),
    #     forward_agent: false,
    #     auth_methods: %w(publickey password)
    #     # password: 'please use keys'
    #   }

The first step is for you to fixRole3 parts:Simple Role Syntaxby placing{[email protected]} instead{[email protected]}Use the following values:

• nodeid- The node ID value of the Apache application server container in your environment.
• uid- numbers before the @ symbol in SSH connections, after which edit the server settings line (in the sectionExtended Server Syntax):
• Specify your SSH host, e.g.Server'gate.manage.Ruk-Com.cloud'
• Enter the value {nodeid}_{uid} for the parameter.usersuch asuser: '190403-136'So your server settings will look like this.

server 'gate.manage.ruk-com.cloud', user: '190403-136', roles: %w{web app}, my_property: :my_value

The final step specifies the server port to be used for SSH connections:

set :ssh_options, {
    port: 3022
}

Don't forget to press the button.Saveto save the manual configuration.

3. OpenCapfile(located in the root folder in your local project) and add this one line:

Rake::Task[:staging].invoke

Configure SSH Agent

1. Make sure you havessh-agentthat is running in your system

2. Add your private SSH key to the agent, which should correspond to the public SSH key you added in the dashboard.

ssh-add {full_path_to_the_necessary_private_SSH_key}

3. You can check if the key was added correctly by entering the commandssh-add -lcommand

Check the configuration

You can make sure everything is configured correctly by going to the root folder on your machine and typing the command below:

cap staging deploy:check

Capistrano will connect to the remote container. Create the required folders in the deploy directory (specified in the set :deploy_to parameter) and check both the remote and local servers for the presence of all required files such as required permissions, tools, etc.

If anything goes wrong You will receive a related error message.

Deploy Application

Proceed to deploy your application by running the command below in the project root folder:

cap staging deploy

Once this is complete, go to the environment URL and make sure your app is successfully deployed.