Aller au contenu

SSH et accès Mis à jour le 2026-05-27

Déploiement Capistrano en SSH

Déployer une application PHP (ou Ruby) vers un environnement Stack Harbor PaaS avec Capistrano — installation, capify, configuration de deploy.rb et exécution de cap deploy en SSH.

Capistrano est un outil Ruby open source qui exécute des scripts sur des serveurs distants via SSH. On l’utilise le plus souvent comme moteur de déploiement — récupérer du Git, poser la nouvelle release sur disque, échanger le lien symbolique current, exécuter les hooks de release, redémarrer l’application. Malgré ses origines Ruby, il déploie n’importe quelle pile, y compris PHP.

Ce guide montre comment déployer une application PHP vers un environnement Stack Harbor PaaS avec Capistrano. Le même flux fonctionne pour Ruby, Node.js ou des sites statiques avec les substitutions évidentes.

Ce qu’il vous faut d’abord

  • Un environnement PHP avec Apache déjà créé sur la plateforme.
  • Une clé SSH publique générée et ajoutée à votre tableau de bord (voir Ajouter une clé SSH).
  • Un dépôt Git contenant votre application PHP. Capistrano 3 ne supporte que Git.
  • Une copie locale du même dépôt.

Toutes les commandes ci-dessous tournent sur votre machine locale sous l’utilisateur dont la clé SSH est enregistrée sur la plateforme. Mélanger les utilisateurs cause des erreurs de permission déconcertantes.

Installer Capistrano

Installez Ruby et Capistrano sur votre machine locale.

sudo apt-get install ruby rubygems
gem install capistrano

(Sur macOS, brew install ruby puis gem install capistrano.)

Capistrano s’attend à trouver un dossier config/ dans votre projet — convention Ruby on Rails. Créez-le s’il n’existe pas :

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

Capify votre application

Depuis la racine du projet, exécutez :

cap install

Cela crée :

  • Capfile — fichier Capistrano principal. Charge les greffons et balise vos tâches personnalisées.
  • config/deploy/ avec staging.rb et production.rb — paramètres par environnement.
  • config/deploy.rb — configuration applicative et instructions Capistrano.
  • lib/capistrano/tasks/ — vos tâches personnalisées.

Configurer config/deploy.rb

Modifiez config/deploy.rb pour correspondre à votre projet. Le minimum :

# Config valide pour Capistrano 3.x
lock '3.2.1'

set :application, 'mon_app'
set :repo_url,    'git@exemple.com:moi/mon_depot.git'

# Où déployer sur le distant (racine PHP par défaut du PaaS)
set :deploy_to, '/var/www/webroot'

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

Quelques notes sur les valeurs :

  • :application — n’importe quelle chaîne. Utilisée dans les chemins distants sous deploy_to.
  • :repo_url — l’URL SSH de votre dépôt Git. L’utilisateur qui lance le déploiement doit avoir une clé SSH publique enregistrée chez l’hôte Git. Pour HTTPS, utilisez set :repo_url, 'https://exemple.net/user/repo.git' pour les dépôts publics ; les dépôts privés HTTPS demandent des identifiants dans l’URL ou un credential helper.
  • :deploy_to — /var/www/webroot est la racine de documents sur les nœuds PHP de la plateforme. Choisissez le dossier correspondant à votre pile.
  • :keep_releases — Capistrano garde les N dernières releases sur disque pour permettre les retours arrière. 5 est un défaut raisonnable.

Ajouter une tâche de redémarrage

Remplacez le bloc namespace :deploy do boilerplate en bas de deploy.rb par une tâche qui redémarre Apache et rafraîchit le lien symbolique de la racine de documents :

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

  desc 'Créer le lien symbolique vers la release courante'
  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

Configurer la liste des serveurs par environnement

Dans config/deploy/production.rb (ou staging.rb), listez les extrémités SSH où Capistrano déploie. Pour le PaaS, l’entrée est la chaîne de connexion SSH Gate envoyée par courriel à l’ajout de la clé SSH, plus le nom d’utilisateur spécifique à votre environnement :

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

Pour plusieurs nœuds applicatifs, listez-les chacun avec les mêmes rôles.

Lancer un déploiement

Depuis la racine du projet :

cap production deploy

Capistrano se connecte en SSH, clone le dépôt dans un nouveau dossier releases/<timestamp>/ sur le distant, exécute les tâches de publication, échange le lien symbolique et redémarre Apache. Le premier déploiement prend environ une minute ; les suivants quelques secondes.

Dépannage

  • Permission denied (publickey). Votre clé SSH locale n’est pas enregistrée chez l’hôte Git, ou la clé publique de l’hôte Git n’est pas dans votre known_hosts. Lancez ssh -T git@exemple.com directement pour vérifier.
  • Impossible de se connecter à la plateforme. Confirmez la chaîne de connexion SSH depuis le courriel du tableau de bord. Testez-la brute : ssh -p <port> <user>@<host>.
  • Apache ne redémarre pas. L’utilisateur Capistrano doit avoir sudo pour service httpd restart — vérifiez avec sudo -n service httpd status en SSH.

Voir aussi