Capistrano

Deploy Applications with Capistrano

Capistrano is an open-source remote automation tool commonly used to deploy applications over SSH. Although it is written in Ruby and frequently associated with Ruby on Rails, it can also be configured to deploy PHP applications to the platform.

In this article

Prerequisites

Before configuring Capistrano, prepare the required environment, repository, and SSH access components.

PHP environment An existing PHP environment with an Apache application server.
SSH key A generated SSH public key that has already been added to the platform dashboard.
Git repository A Git repository containing the PHP application. Capistrano 3 supports Git for this workflow.
Local project copy A local copy of the application repository on the computer from which deployment will be performed.
!

Run commands as the correct local user

Execute the commands under the same local user account that was used to generate the SSH key pair. This helps prevent permission and SSH connection errors.

Install Capistrano

1

Install Ruby and RubyGems on the local computer.

apt-get install ruby rubygems
2

Install Capistrano through RubyGems.

gem install capistrano
3

Ensure that the project contains a config directory. Create it when it does not already exist.

mkdir {path_to_your_project}/config

Capify the Application

After installing Capistrano, initialize its deployment structure in the root directory of the local PHP project.

cap install

The command creates the standard Capistrano files and folders:

Capfile The primary Capistrano file used to load configuration and custom task definitions.
config/deploy/ Contains environment-specific configuration files such as staging.rb and production.rb.
config/deploy.rb Contains the main application deployment settings and Capistrano instructions.
lib/capistrano/tasks/ Stores custom Capistrano tasks.

Configure config/deploy.rb

Open config/deploy.rb and update the application, repository, deployment directory, source-control, output, and terminal settings.

Set the application name

set :application, “my_app_name”

Set the Git repository URL

set :repo_url, “git@example.net:me/my_repo.git”
!

Repository SSH access

The SSH public key associated with the local private key must also be attached to the Git account. Otherwise, deployment may fail with a permission-denied error.

A public HTTPS repository URL can be used when repository authentication is not required:

set :repo_url, “https://example.net/GIT_user_name/repo_name.git”

Set the deployment directory

Use the default web-root location for the platform PHP application server:

set :deploy_to, ‘/var/www/webroot’

Enable the required Capistrano options

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

Replace the default deployment tasks

Remove the default task block beginning with namespace :deploy do and replace it with the following tasks:

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’

Additional options, such as a repository branch, linked files, or linked directories, can be included when required by the application.

Configure config/deploy/staging.rb

Open config/deploy/staging.rb and replace the default server identities with the platform SSH connection values.

Update the role entries

For each role line, replace deploy@example.com with the platform SSH identity in this format:

{nodeid}-{uid}@{your.SSH.host}
nodeid The node ID of the Apache application server container.
uid The numeric account identifier shown before the @ symbol in the SSH connection string.
SSH host The SSH gateway hostname provided by the platform.

The application, web, and database role entries should use the same target when the application is deployed to a single Apache node.

Update the server definition

Specify the SSH gateway hostname and use the combined nodeid-uid value as the user.

server ‘gate.jelastic.com’, user: ‘190403-136’, roles: %w{web app}, my_property: :my_value

Set the SSH port

set :ssh_options, { port: 3022 }
✓

Save the file

Save all staging configuration changes before continuing to the Capfile and SSH-agent configuration.

Update the Capfile

Open the Capfile in the root of the local project and add the following line:

Rake::Task[:staging].invoke

Configure the SSH Agent

1

Confirm that ssh-agent is running on the local system.

2

Add the private SSH key that corresponds to the public key uploaded to the platform dashboard.

ssh-add {full_path_to_the_necessary_private_SSH_key}
3

Verify that the required key is loaded.

ssh-add -l

Check the Configuration

From the root directory of the local project, run the Capistrano deployment check:

cap staging deploy:check

Capistrano connects to the remote application container, prepares the required deployment folders, and validates the local and remote requirements. Missing tools, files, permissions, or configuration details are reported as errors.

Deploy the Application

After the configuration check completes successfully, deploy the application from the project root:

cap staging deploy

Capistrano downloads the repository, creates the release structure, updates the current-release link, creates the platform web-root symlink, and restarts Apache according to the configured tasks.

✓

Deployment verification

Open the environment URL after deployment and confirm that the application loads correctly.

Related Documentation