Hoe gebruik ik Capistrano 3.x?

In het kort:

Voeg capistrano-rails, capistrano-passenger en capistrano-rvm toe aan Gemfile
Installeer Capistrano
Werk de configuratie-scripts bij

In detail:

Start met het toevoegen van de benodigde gems aan de Gemfile:

Gemfile

group :development, :test do
gem 'capistrano-passenger'
gem 'capistrano-rails'
gem 'capistrano-rvm'
end

Installeer de gems:

$ bundle install

Installeer Capistrano:

$ cap install

Vul de standaard-configuratie van Capistrano aan met specifieke configuratie voor uw omgeving. Om te beginnen activeren we Capistrano-rvm en Capistrano-passenger. Voer wijzigingen door in Capfile, zodat deze lijkt op:

Capfile

# Load DSL and set up stages
require "capistrano/setup"

# Include default deployment tasks
require "capistrano/deploy"

# Include tasks from other gems included in your Gemfile
require 'capistrano/rvm'
require 'capistrano/bundler'
require 'capistrano/rails/assets'
require 'capistrano/rails/migrations'
require 'capistrano/passenger'

# Load custom tasks from `lib/capistrano/tasks` if you have any defined
Dir.glob("lib/capistrano/tasks/*.rake").each { |r| import r }

In het bestand config/deploy.rb staan gegevens als de naam van de applicatie, het GIT repository url en de Ruby versie.

Shared hosting omgevingen zijn voorzien van meerdere Ruby versies. U heeft bij uw bestelling aangegeven welke Ruby versie u wenst te gebruiken. Het is dus belangrijk om deze Ruby versie ook op te nemen in uw configuratie, ook als u lokaal geen rvm gebruikt. Het is handig om deze versie in .ruby-version op te slaan. Merk op dat wanneer u een nieuwere versie wilt gebruiken u de server-configuratie laat aanpassen.

.ruby-version

2.5.1

config/deploy.rb

lock '3.11.0'

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

set :rvm_ruby_version, File.open(File.dirname(__FILE__) + '/../.ruby-version').read.strip
set :pty, true

set :ssh_options, forward_agent: true

append :linked_files, 'config/database.yml', 'config/secrets.yml'
append :linked_dirs, 'log', 'tmp/pids', 'tmp/cache', 'tmp/sockets', 'public/system'

Per omgeving (staging, production) heeft Capistrano een configuratie-bestand aangemaakt. Afhankelijk van uw pakket kunt u dit bestand wijzigen in:

config/deploy/production.rb

role :app, %w(gebruiker@server)
role :web, %w(gebruiker@server)
role :db,  %w(gebruiker@server)

set :deploy_to, '/var/www/vhosts/<naam van website>/rails'
set :branch, :production

Om er zeker van te zijn dat Capistrano vanaf onze server uw Git repository kunt bereiken kunt u via ssh verbinden naar uw account en vervolgens vanuit daar een verbinding maken naar uw git server.

Indien uw code bij Github staat doet u dat bijvoorbeeld met het volgende commando:

$ ssh -t gebruiker@server ssh git@github.com

Na het accepteren van de host key zou Github u moeten herkennen. Zo niet, dan dient u eerst nog agent forwarding in te schakelen op uw lokale omgeving.

Controleer of de configuratie op orde is:

$ cap production deploy:check

Maak de doel-omgeving gereed:

$ cap production deploy:setup

Capistrano heeft nu op de server een aantal mappen gemaakt om vervolgens een uitvoer te kunnen maken. Afhankelijk van het pakket kan het nodig zijn nog een rails/shared/config/database.yml en rails/shared/config/secrets.yml aan te maken. Deze bestanden hebben een inhoud die lijkt op:

rails/shared/config/database.yml (op de server)

production:
  host: localhost
  username: ...
  password: ...
  database: ...
  adapter: postgresql
  pool: 25
  encoding: utf8

rails/shared/config/secrets.yml (op de server)

production:
  secret_key_base: <geheim token>

Maak eventueel een nieuw geheim token met een Rails-taak:

$ rails secret

Om nu uit te rollen is enkel nog nodig Capistrano deploy-taak uit te voeren:

$ cap production deploy

De belangrijkste Capistrano commando’s op een rij

Met Capistrano hoeft u nooit zelf een verbinding te maken met de Bluerail servers om uw applicatie te updaten. U voert alle commando’s uit vanuit de lokale kopie van uw Rails applicatie. Hieronder vindt u een kort overzicht van de belangrijkste commando’s:

cap <omgeving> deploy:setup: Met dit commando maakt u de benodigde directorystructuur voor Capistrano op de server aan. Dit commando dient altijd uitgevoerd te worden bij het in gebruik nemen van een nieuw hosting account.
cap <omgeving> deploy: Om nieuwe versies op de server uit te rollen volstaat het cap deploy commando. Indien u de bovenstaande config.rb gebruikt wordt tevens automatisch de bundle bijgewerkt.
cap <omgeving> deploy:migrations: Deze taak installeert niet alleen een nieuwe versie van de applicatie maar voert tevens de databasemigraties uit.
cap <omgeving> deploy:rollback: Mocht een deployment onverwacht tot problemen leiden, dan kunt u met rollback terug naar de vorige release.
cap <omgeving> deploy:cleanup: Als een deployment succesvol is verlopen kunt u met cap deploy:cleanup oude releases van de applicatie van de server verwijderen om zo schijfruimte te besparen. Het aantal versies dat bewaard wordt kunt u instellen met de keep_releases-optie in deploy.rb

Bluerail

FAQ

Veelgestelde vragen

Hoe gebruik ik Capistrano 3.x?

In het kort:

In detail:

De belangrijkste Capistrano commando’s op een rij

Storing, vragen of opmerkingen?