Skip to content

SSH and Access Updated 2026-05-27

Capistrano deployment over SSH

Deploy a PHP (or Ruby) application to a Stack Harbor PaaS environment with Capistrano — install, capify, configure deploy.rb, and run cap deploy over SSH.

Capistrano is an open-source Ruby tool for executing scripts on remote servers over SSH. It is most often used as a deployment driver — pull from Git, lay out the new release on disk, swap the current symlink, run release hooks, restart the application. Despite the Ruby origins, it deploys any stack, including PHP.

This guide walks through deploying a PHP application to a Stack Harbor PaaS environment with Capistrano. The same flow works for Ruby, Node.js, or static sites with the obvious substitutions.

What you need first

  • A PHP environment with Apache already created on the platform.
  • An SSH public key generated and added to your dashboard (see Add an SSH key).
  • A Git repository containing your PHP application. Capistrano 3 supports Git only.
  • A local checkout of the same repository.

All commands below run on your local machine as the user whose SSH key you registered with the platform. Mixing users causes confusing permission errors.

Install Capistrano

Install Ruby and Capistrano on your local machine.

sudo apt-get install ruby rubygems
gem install capistrano

(On macOS, brew install ruby and then gem install capistrano.)

Capistrano expects a config/ folder inside your project — Ruby on Rails convention. Create it if it doesn’t exist:

mkdir -p path/to/your/project/config

Capify your application

From the project root, run:

cap install

This creates:

  • Capfile — top-level Capistrano file. Loads plugins and globs your custom tasks.
  • config/deploy/ with staging.rb and production.rb — per-environment settings.
  • config/deploy.rb — application configuration and Capistrano instructions.
  • lib/capistrano/tasks/ — your custom tasks.

Configure config/deploy.rb

Edit config/deploy.rb to match your project. The minimum:

# config valid for Capistrano 3.x
lock '3.2.1'

set :application, 'my_app_name'
set :repo_url,    'git@example.com:me/my_repo.git'

# Where to deploy on the remote (default PaaS PHP app root)
set :deploy_to, '/var/www/webroot'

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

A few notes on the values:

  • :application — any string. Used in remote paths under deploy_to.
  • :repo_url — the SSH URL to your Git repo. The user running the deploy needs an SSH public key on the Git host. If you prefer HTTPS, use set :repo_url, 'https://example.net/user/repo.git' for public repositories; private HTTPS repos require credentials in the URL or a credential helper.
  • :deploy_to — /var/www/webroot is the document root on the platform’s PHP nodes. Pick the matching directory for your stack.
  • :keep_releases — Capistrano keeps the last N releases on disk so you can roll back. 5 is a reasonable default.

Add a restart task

Replace the boilerplate namespace :deploy do block at the bottom of deploy.rb with a task that restarts Apache and refreshes the document-root symlink:

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

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

  after :publishing, :symlink
  after :symlink, :apache
end

Configure environment server lists

In config/deploy/production.rb (or staging.rb), list the SSH endpoints Capistrano deploys to. For the PaaS, the entry is the SSH Gate connection string emailed to you when you added the SSH key, plus your environment-specific username:

server '<ssh_gate_host>',
       user: '<ssh_gate_user>',
       roles: %w{app web},
       port: <ssh_gate_port>

For multiple application nodes, list each one with the same roles.

Run a deploy

From the project root:

cap production deploy

Capistrano connects over SSH, clones the repo into a new releases/<timestamp>/ directory on the remote, runs the publishing tasks, swaps the symlink, and restarts Apache. The first deploy takes a minute or so; subsequent deploys are typically a few seconds.

Troubleshooting

  • Permission denied (publickey). Your local SSH key is not registered with the Git host, or the Git host’s public key is not in your known_hosts. Run ssh -T git@example.com directly to verify.
  • Cannot connect to the platform host. Confirm the SSH connection string from the dashboard email. Test it raw: ssh -p <port> <user>@<host>.
  • Apache fails to restart. The Capistrano user needs sudo to run service httpd restart — verify with sudo -n service httpd status over SSH.

See also