Autor: [Piotr Wasilewski](/autorzy/piotr-wasilewski) Architekt rozwiązań chmurowych · Zweryfikowano Kwiecień 2026

1.  [Strona główna](/) ›
2.  [Baza wiedzy](/baza-wiedzy/) ›
3.  Capistrano: deployment Rails i PHP

# 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, 'git@github.com: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

Cecha

Capistrano

Kamal

Rok powstania

2006

2023

Model deploymentu

Git clone + symlink

Docker image

Reverse proxy

Zewnętrzny (Nginx)

Wbudowany (Traefik)

Zero-downtime

Tak (symlink switch)

Tak (container rotate)

SSL/TLS

Ręcznie (certbot)

Automatyczny (Let's Encrypt)

Wymaga Rubiego

Tak

Tak (tylko lokalnie)

## 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

Do czego służy Capistrano? +

Capistrano to narzędzie do automatycznego deploymentu aplikacji (najczęściej Ruby on Rails, ale również PHP, Node.js). Wykonuje deploy przez SSH, zarządza wersjami, shared files, symlinks i umożliwia rollback jedną komendą.

Jak działa rollback w Capistrano? +

Capistrano utrzymuje katalog releases/ z ostatnimi 5 wdrożeniami i symlink current wskazujący na aktywną wersję. Rollback to zmiana symlinka na poprzedni release (cap production deploy:rollback) — dzieje się w ułamku sekundy i bez przerwy w działaniu.

Co to są shared folder i linked files? +

Shared folder to katalog utrzymywany między deploymentami (np. uploads/, log/, tmp/). Linked files to pojedyncze pliki (np. database.yml, .env), które są symlinkowane z shared do każdego nowego release — dzięki temu konfiguracja jest spójna.

Czy Kamal zastępuje Capistrano? +

Kamal (od DHH, twórca Rails) to nowsze narzędzie deployment dla aplikacji Dockerowych. Dla kontenerów Kamal jest lepszy (prostszy, zero-downtime z Traefik). Dla klasycznych Rails bez Dockera Capistrano dalej jest standardem.

## Sprawdź oferty pasujące do tego scenariusza

Poniżej masz szybkie przejścia do ofert i stron z kodami rabatowymi tam, gdzie są dostępne.

Contabo

VPS z rootem i dużym dyskiem — pomieści wiele releasów Capistrano bez problemu.

VPS

[Aktywuj rabat →](/out/contabo)

#Reklama · link partnerski

[Zobacz kod rabatowy →](/kody-rabatowe/contabo)

LH.pl

Hosting SSH — możesz używać Capistrano nawet na shared hostingu przy prostszych aplikacjach.

Hosting

[Aktywuj rabat →](/out/lh-pl)

#Reklama · link partnerski

[Zobacz kod rabatowy →](/kody-rabatowe/lh-pl)

Mikrus

Tani VPS do testów deploymentów Capistrano i eksperymentów z roles.

Dev/Test

[Aktywuj rabat →](/out/mikrus)

#Reklama · link partnerski

[Zobacz kod rabatowy →](/kody-rabatowe/mikrus)

## Powiązane strony

-   [Zero-downtime deployment z Nginx](/baza-wiedzy/zero-downtime-deployment-nginx)
-   [GitHub Actions: deployment na VPS](/baza-wiedzy/github-actions-deployment-vps)
-   [PM2 cluster mode dla Node.js](/baza-wiedzy/pm2-cluster-mode-nodejs)
-   [Wszystkie artykuły](/baza-wiedzy/)