Capistrano: deployment Rails i PHP — pełny przewodnik

Opublikowano: 9 kwietnia 2026 · Kategoria: DevOps

Capistrano to weteran świata deploymentów — narzędzie napisane w Ruby, używane od 2006 roku do wdrażania aplikacji Ruby on Rails, ale działające również z PHP (Laravel, Symfony), Node.js, Pythonem i innymi stosami. Capistrano automatyzuje proces deploymentu przez SSH, zarządza wersjami wdrożeń, umożliwia rollback jedną komendą i zapewnia zero-downtime przez atomic symlink switching.

Struktura katalogów Capistrano

Po pierwszym deploymencie Capistrano tworzy na serwerze charakterystyczną strukturę katalogów. Zrozumienie jej jest kluczowe — wokół tej konwencji zbudowany jest cały mechanizm wersjonowania i rollbacku.

/var/www/myapp/
├── current -> releases/20260409120000   # symlink na aktywna wersje
├── releases/                              # historia deploymentow (domyslnie 5)
│   ├── 20260409120000/                    # biezacy release
│   ├── 20260408093000/
│   ├── 20260407154500/
│   ├── 20260406110000/
│   └── 20260405080000/
├── shared/                                # pliki wspoldzielone miedzy releasami
│   ├── config/
│   │   ├── database.yml                   # symlink target dla linked_files
│   │   ├── master.key
│   │   └── .env
│   ├── log/
│   ├── tmp/
│   ├── public/uploads/                    # user-generated content
│   └── vendor/bundle/                     # gems (aby nie instalowac za kazdym razem)
└── repo/                                  # git repository cache

Cały urok tego podejścia polega na tym, że symlink current jest zmieniany atomowo dopiero po pełnym zbudowaniu nowego releasu. Przez cały czas trwania deploymentu ruch użytkowników idzie do poprzedniej wersji — a po zamianie symlinka kolejne requesty trafiają już na nową. Zero przerwy, zero problemów z half-deployed state.

Instalacja i konfiguracja

Capistrano instalujesz jako gem, a konfiguracja żyje w plikach Capfile, config/deploy.rb (globalne) oraz config/deploy/production.rb (per-environment).

# Dodaj do Gemfile (group :development)
gem 'capistrano', '~> 3.18'
gem 'capistrano-rails', '~> 1.6'
gem 'capistrano-bundler', '~> 2.1'
gem 'capistrano-rbenv', '~> 2.2'

bundle install

# Zainicjalizuj strukture Capistrano
bundle exec cap install STAGES=production,staging

# Utworzy:
# Capfile
# config/deploy.rb
# config/deploy/production.rb
# config/deploy/staging.rb
# lib/capistrano/tasks/

Główny plik konfiguracyjny config/deploy.rb zawiera ustawienia wspólne dla wszystkich środowisk: nazwa aplikacji, repozytorium Git, shared files, keep_releases (ile historycznych releasów trzymać). Plik config/deploy/production.rb definiuje konkretne serwery i role dla środowiska produkcyjnego.

Tasks i roles

Capistrano używa konceptu roles do grupowania serwerów według funkcji (app, web, db, jobs). Dzięki temu możesz mieć wielomaszynowy deployment, gdzie migracje są uruchamiane tylko na serwerze z rolą db, a restart puma-y tylko na serwerach z rolą app.

# config/deploy.rb
set :application, 'myapp'
set :repo_url, '[email protected]:user/myapp.git'
set :deploy_to, '/var/www/myapp'
set :keep_releases, 5

set :linked_files, %w{config/database.yml config/master.key .env}
set :linked_dirs, %w{log tmp/pids tmp/cache tmp/sockets vendor/bundle public/uploads}

set :rbenv_ruby, '3.3.0'

# config/deploy/production.rb
server '203.0.113.10', user: 'deploy', roles: %w{app web db}, primary: true
server '203.0.113.11', user: 'deploy', roles: %w{app web}
server '203.0.113.12', user: 'deploy', roles: %w{jobs}

set :ssh_options, {
  keys: %w(~/.ssh/deploy_key),
  forward_agent: true,
  auth_methods: %w(publickey)
}

# Custom task
namespace :deploy do
  desc 'Restart Sidekiq'
  task :restart_sidekiq do
    on roles(:jobs) do
      execute :sudo, :systemctl, :restart, :sidekiq
    end
  end

  after :publishing, :restart_sidekiq
end

Porównanie Capistrano vs Kamal

Deploy, rollback i najczęstsze komendy

Capistrano jest wywoływane przez komendę cap z argumentem stage. Najczęściej używane komendy to cap production deploy (pełny deployment) oraz cap production deploy:rollback (cofnięcie do poprzedniego releasu).

# Pelny deployment
bundle exec cap production deploy

# Rollback do poprzedniego release
bundle exec cap production deploy:rollback

# Sprawdz aktualna wersje na serwerze
bundle exec cap production deploy:check

# Zaladuj tylko konkretny plik do shared
bundle exec cap production deploy:check:linked_files

# Custom task (np. restart Sidekiq)
bundle exec cap production deploy:restart_sidekiq

# Dry-run (zobacz co bedzie wykonane)
bundle exec cap production deploy --dry-run

# Debug z verbose output
bundle exec cap production deploy --trace

Typowy cykl deploymentu Capistrano to: git pull do repo/, copy do releases/TIMESTAMP/, bundle install, rails assets:precompile, migracje bazy (z flagą conditional), symlink current na nowy release, restart aplikacji (puma/unicorn/passenger), cleanup starych releasów.

Najczęstsze pytania