Otomatik Ruby On Rails Uygulama Dağıtımları: Capistrano Rehberi

Ruby on Rails uygulamaları geliştirmek keyifli ve verimlidir, ancak uygulamanızı canlıya almak (deployment) süreci manuel olarak yapıldığında sıkıcı, zaman alıcı ve hataya açık olabilir. Sürekli entegrasyon ve sürekli dağıtım (CI/CD) pratiğinin ayrılmaz bir parçası olan otomatik dağıtımlar, bu sorunları ortadan kaldırarak geliştiricilerin daha çok kod yazmaya odaklanmasını sağlar. Capistrano, Rails uygulamaları için özel olarak tasarlanmış, SSH üzerinden sunuculara komutlar göndererek dağıtım sürecini otomatikleştiren güçlü bir araçtır. Bu rehberde, Capistrano’yu kullanarak Rails uygulamanızın dağıtımını nasıl otomatikleştireceğinizi adım adım öğreneceksiniz.

Capistrano Nedir ve Neden Kullanmalısınız?

Capistrano, Ruby ile yazılmış, uzak sunucularda komut dosyalarını çalıştırmak için tasarlanmış bir otomasyon aracıdır. Özellikle Rails uygulamalarının dağıtımı için popülerdir çünkü:

Tutarlılık: Dağıtım süreçlerini standartlaştırarak her seferinde aynı adımların izlenmesini sağlar, bu da insan hatalarını minimize eder.
Hız: Manuel adımları otomatikleştirerek dağıtım süresini önemli ölçüde kısaltır.
Güvenilirlik: Otomatikleştirilmiş süreçler daha az hataya açıktır. Ayrıca, Capistrano’nun yerleşik geri alma (rollback) yetenekleri sayesinde hatalı bir dağıtım durumunda kolayca önceki sürüme dönebilirsiniz.
Esneklik: Farklı ortamlara (staging, production) ve birden fazla sunucuya aynı anda dağıtım yapma yeteneği sunar.
Entegrasyon: Git, Bundler, RVM/rbenv, Puma/Passenger gibi birçok Rails ekosistemi aracıyla sorunsuz entegrasyon sağlar.

Capistrano, SSH aracılığıyla sunucularınıza bağlanır ve tanımladığınız görevleri çalıştırır. Bu görevler, genellikle Git deposundan kodu çekme, bağımlılıkları yükleme, veritabanı geçişlerini (migrations) çalıştırma, varlıkları (assets) ön derleme ve uygulama sunucusunu yeniden başlatma gibi adımları içerir. Uygulamanızın her yeni sürümü ayrı bir dizine dağıtılır ve mevcut sürüm, sembolik bir bağlantı (symlink) ile işaret edilir. Bu yapı, geri alma işlemlerini son derece kolaylaştırır.

Capistrano ile Rails Uygulamasını Yapılandırma

Capistrano’yu uygulamanıza entegre etmek ve dağıtım sürecini yapılandırmak birkaç adımdan oluşur. Başlamadan önce, sunucunuzda SSH erişiminizin, Git’in ve Ruby’nin kurulu olduğundan emin olun. Ayrıca, sunucunuzda uygulamanızı dağıtmak için özel bir kullanıcı (örneğin, deploy) oluşturmak iyi bir güvenlik pratiğidir.

Adım 1: Capistrano Kurulumu

Rails uygulamanızın Gemfile‘ına Capistrano gem’ini ve gerekli eklentileri ekleyin:


Gemfile
group :development do
  gem 'capistrano', '~> 3.17'
  gem 'capistrano-rails', '~> 1.7'
  gem 'capistrano-rbenv', '~> 2.2' # Veya capistrano-rvm
  gem 'capistrano-bundler', '~> 2.1'
  gem 'capistrano-puma', '~> 5.5' # Veya capistrano-passenger, capistrano-unicorn
end

Daha sonra, gem’leri yükleyin:


bundle install

Şimdi Capistrano’yu projenize entegre edin. Bu komut, gerekli Capistrano yapılandırma dosyalarını oluşturacaktır:


cap install

Bu komut aşağıdaki dosyaları oluşturur:

Capfile: Capistrano’nun ana yapılandırma dosyasıdır. Hangi görevlerin yükleneceğini belirtir.
config/deploy.rb: Tüm ortamlar için genel dağıtım ayarlarını içerir.
config/deploy/staging.rb: Staging ortamına özel ayarlar.
config/deploy/production.rb: Production ortamına özel ayarlar.

Adım 2: `Capfile` Yapılandırması

Capfile dosyası, Capistrano’nun hangi eklentileri ve görevleri yüklemesi gerektiğini söyler. cap install komutu genellikle temel yapılandırmayı yapar, ancak kullandığınız tüm eklentilerin burada require edildiğinden emin olun.


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

Include default deployment tasks
require "capistrano/deploy"

Load the SCM plugin for Git (default)
require "capistrano/scm/git"

Load the Rails plugin
require "capistrano/rails"
require "capistrano/bundler"
require "capistrano/rbenv" # Veya capistrano/rvm
require "capistrano/puma" # Veya kullandığınız uygulama sunucusu
require "capistrano/passenger"
require "capistrano/unicorn"

Custom tasks that you might want to load
Dir.glob("lib/capistrano/tasks/*.rake").each { |r| import r }

Adım 3: `config/deploy.rb` Yapılandırması

Bu dosya, tüm dağıtım ortamları için geçerli olan temel ayarları içerir.


config/deploy.rb
lock "~> 3.17"

set :application, "my_rails_app" # Uygulamanızın adı
set :repo_url, "git@github.com:kullaniciadi/depoadi.git" # Git deponuzun URL'si

Varsayılan branch
set :branch, ENV['BRANCH'] || 'main'

Uygulamanın sunucuda dağıtılacağı yol
set :deploy_to, "/var/www/#{fetch(:application)}"

Sunucudaki Ruby versiyon yönetimi (rbenv veya rvm)
set :rbenv_type, :user # Veya :system
set :rbenv_ruby, '3.2.2' # Kullandığınız Ruby versiyonu
set :rbenv_path, "~/.rbenv" # rbenv kurulum yolunuz

Ortak dizinler ve dosyalar. Bunlar her yeni dağıtımda korunur.
Hassas bilgileri (veritabanı şifreleri, API anahtarları) buraya ekleyin.
set :linked_files, %w{config/database.yml config/master.key config/credentials/production.key}
set :linked_dirs, %w{log tmp/pids tmp/cache tmp/sockets vendor/bundle public/system public/uploads}

Kaç adet eski sürümün saklanacağını belirtir.
set :keep_releases, 5

Log seviyesi: :debug, :info, :warn, :error
set :log_level, :info

SSH agent forwarding'i etkinleştirin. Bu, sunucunun Git deposuna erişmek için
yerel makinenizin SSH anahtarlarını kullanmasına izin verir.
set :ssh_options, {
  forward_agent: true,
  auth_methods: %w[publickey]
}

Puma sunucuya özel ayarlar (eğer capistrano-puma kullanıyorsanız)
set :puma_init_active_record, true
set :puma_workers, 2
set :puma_threads, [2, 8] # min, max
set :puma_bind, "unix://#{shared_path}/tmp/sockets/puma.sock"
set :puma_state, "#{shared_path}/tmp/pids/puma.state"
set :puma_pid, "#{shared_path}/tmp/pids/puma.pid"
set :puma_access_log, "#{shared_path}/log/puma.access.log"
set :puma_error_log, "#{shared_path}/log/puma.error.log"

Dağıtım sonrası veritabanı geçişlerini çalıştırmak için
after 'deploy:publishing', 'puma:restart' # Veya 'passenger:restart', 'unicorn:restart'

Adım 4: Ortama Özel Yapılandırma (`config/deploy/production.rb`)

Şimdi üretim ortamına özel ayarları yapalım. Staging için de benzer bir dosya oluşturabilirsiniz.


config/deploy/production.rb
server 'your_production_server_ip_or_hostname', user: 'deploy', roles: %w{web app db}

set :rails_env, :production # Rails ortamını belirtir
set :deploy_to, "/var/www/#{fetch(:application)}_production" # Ortama özel dağıtım yolu

SSH portu farklıysa
set :ssh_options, { port: 2222 }

your_production_server_ip_or_hostname kısmını sunucunuzun IP adresi veya alan adıyla, deploy kısmını ise sunucunuzdaki dağıtım kullanıcınızla değiştirin. roles kısmı, sunucunun hangi rolleri üstlendiğini belirtir (web sunucusu, uygulama sunucusu, veritabanı sunucusu).

Pratik Bilgi: linked_files ve linked_dirs Capistrano’nun en önemli özelliklerinden biridir. Bu ayarlar sayesinde, config/database.yml gibi sunucuya özel veya hassas dosyalar ile log, tmp, public/uploads gibi her dağıtım arasında kalması gereken dizinler, her yeni sürümde yeniden oluşturulmaz, bunun yerine shared dizininden sembolik olarak bağlanır. Bu dosyaları ve dizinleri shared dizinine manuel olarak ilk kez kopyalamanız gerekir.


Sunucuda ilk kez dağıtımdan önce
mkdir -p /var/www/my_rails_app_production/shared/config
Kendi database.yml ve master.key dosyalarınızı sunucuya kopyalayın
scp config/database.yml deploy@your_server_ip:/var/www/my_rails_app_production/shared/config/database.yml
scp config/master.key deploy@your_server_ip:/var/www/my_rails_app_production/shared/config/master.key
Eğer Rails 6+ kullanıyorsanız, production.key'i de kopyalayın
scp config/credentials/production.key deploy@your_server_ip:/var/www/my_rails_app_production/shared/config/credentials/production.key

Uygulama Dağıtımı ve Yönetimi

Yapılandırma tamamlandıktan sonra, uygulamanızı dağıtmaya hazırsınız.

İlk Dağıtım

Uygulamanızı ilk kez dağıtırken, Capistrano gerekli tüm dizinleri oluşturacak, depoyu klonlayacak, bağımlılıkları yükleyecek ve varlıkları ön derleyecektir.


cap production deploy

Bu komutun başarıyla tamamlanmasının ardından, uygulamanız belirtilen sunucu yolunda çalışıyor olmalıdır. Uygulama sunucunuzun (Puma, Nginx, Apache vb.) doğru yapılandırıldığından ve Capistrano’nun başlattığı uygulamayı işaret ettiğinden emin olun.

Sonraki Dağıtımlar

Uygulamanızda değişiklikler yaptıktan sonra, yeni sürümü dağıtmak için aynı komutu kullanmanız yeterlidir:


cap production deploy

Capistrano, sadece değişen dosyaları çekecek, gerekli güncellemeleri yapacak ve uygulama sunucusunu yeniden başlatacaktır. Bu süreç, uygulamanızın kesintisiz bir şekilde güncellenmesini sağlar.

Geri Alma (Rollback)

Bir dağıtımın ardından bir sorunla karşılaşırsanız, Capistrano sayesinde kolayca önceki çalışan sürüme geri dönebilirsiniz:


cap production deploy:rollback

Bu komut, current sembolik bağlantısını bir önceki sürüme çevirir ve uygulama sunucusunu yeniden başlatır. Veritabanı geçişleri geri alınmaz, bu nedenle veritabanı şemasını bozan bir değişiklik yaptıysanız, manuel olarak geri almanız gerekebilir.

Diğer Faydalı Komutlar

Dağıtım Öncesi Kontrol:
```
cap production deploy:check
        
```
Bu komut, sunucuda gerekli dizinlerin, izinlerin ve Git erişiminin olup olmadığını kontrol eder.
Uygulama Sunucusunu Yeniden Başlatma:
```
cap production puma:restart # Veya passenger:restart, unicorn:restart
        
```
Uygulamanızı manuel olarak yeniden başlatmanız gerektiğinde kullanılır.
Rails Konsoluna Bağlanma:
```
cap production rails:console
        
```
Uzak sunucudaki uygulamanızın Rails konsoluna bağlanmanızı sağlar.
Sunucu Loglarını İzleme:
```
cap production log:tail
        
```
Uygulama loglarını gerçek zamanlı olarak izlemenizi sağlar (capistrano-log_with_tag gem’i ile daha gelişmiş izleme mümkündür).

Pratik İpuçları:

* SSH Anahtarları ve deploy Kullanıcısı: Her zaman bir deploy kullanıcısı oluşturun ve bu kullanıcıya sudo yetkisi vermeyin. Git deposuna erişim için SSH anahtarları kullanın ve yerel makinenizin anahtarlarını sunucuya ssh-copy-id ile kopyalayın. forward_agent: true ayarı, yerel makinenizin SSH anahtarını sunucuda kullanmanıza olanak tanır.
* Ortam Değişkenleri: Hassas API anahtarları gibi ortam değişkenlerini doğrudan deploy.rb dosyasına yazmaktan kaçının. Bunun yerine, config/master.key veya config/credentials/production.key gibi Rails’in şifreli kimlik bilgileri mekanizmasını kullanın veya sunucu tarafında ENV değişkenleri olarak ayarlayın.
* Nginx/Apache Yapılandırması: Capistrano yalnızca Rails uygulamasını dağıtır ve çalıştırır. Nginx veya Apache gibi bir web sunucusunu uygulamanıza yönlendirmek için manuel olarak yapılandırmanız gerekir. Genellikle web sunucusunun yapılandırmasında current/public dizinini işaret etmeniz gerekir.
* Veritabanı Oluşturma: İlk dağıtımda veritabanı henüz oluşturulmamışsa, cap production rake db:create komutunu manuel olarak çalıştırmanız gerekebilir.

Sonuç ve Sıkça Sorulan Sorular

Capistrano, Ruby on Rails uygulamalarının dağıtım sürecini otomatikleştirmek için vazgeçilmez bir araçtır. Doğru yapılandırıldığında, dağıtımları hızlı, tutarlı ve güvenilir hale getirerek geliştirme ekibinizin verimliliğini önemli ölçüde artırır. İlk başta biraz öğrenme eğrisi olsa da, sunduğu avantajlar bu çabaya değerdir.

Sıkça Sorulan Sorular (SSS)

S: Capistrano neden diğer dağıtım araçlarından daha iyi?

C: Capistrano, Rails ekosistemiyle derinlemesine entegre olması, Ruby tabanlı olması ve güçlü, esnek bir DSL (Domain Specific Language) sunması nedeniyle Rails uygulamaları için doğal bir seçimdir. Geri alma yetenekleri ve basit sunucu yönetimi, onu özellikle cazip kılar.

S: Veritabanı şifreleri ve API anahtarları gibi hassas bilgileri nasıl yönetirim?

C: Bu tür hassas bilgileri config/database.yml ve config/master.key gibi dosyalara yerleştirin ve bu dosyaları linked_files array’ine ekleyin. Bu dosyalar Git deposunda saklanmamalı, bunun yerine ilk dağıtımda shared/config dizinine manuel olarak kopyalanmalıdır. Rails 6+ kullanıyorsanız, config/credentials/production.key dosyasını da kullanabilirsiniz.

S: Dağıtım sırasında sık karşılaşılan hatalar nelerdir ve nasıl giderilir?

SSH Bağlantı Sorunları: deploy kullanıcısının sunucuya SSH anahtarlarıyla erişebildiğinden emin olun. ssh -vvv deploy@your_server_ip komutuyla detaylı hata ayıklama yapabilirsiniz.
İzin Sorunları: deploy_to dizinine ve alt dizinlerine deploy kullanıcısının yazma izni olduğundan emin olun.
Gem Yükleme Hataları: Sunucudaki Ruby versiyonunun ve Bundler’ın doğru çalıştığından emin olun. cap production deploy:check komutu yardımcı olabilir.
Varlık (Asset) Ön Derleme Hataları: RAILS_ENV=production bundle exec rake assets:precompile komutunu yerel olarak çalıştırarak hataları tespit edebilirsiniz. JavaScript çalışma zamanının (Node.js gibi) sunucuda kurulu olduğundan emin olun.
Veritabanı Yapılandırma Hataları: shared/config/database.yml dosyasının doğru yapılandırıldığından ve veritabanı kullanıcısının gerekli izinlere sahip olduğundan emin olun.

Hata mesajlarını dikkatlice okuyun ve set :log_level, :debug ayarını geçici olarak kullanarak daha fazla bilgi edinin.

S: Birden fazla sunucuya dağıtım yapabilir miyim?

C: Evet, Capistrano’nun temel özelliklerinden biridir. config/deploy/production.rb dosyanızda birden fazla server tanımı yaparak veya farklı rollere sahip sunucuları belirterek bunu yapabilirsiniz.

S: Dağıtım sonrası özel komutlar çalıştırmak mümkün mü?

C: Kesinlikle! Capistrano’nun görev kancalarını (hooks) kullanarak dağıtım sürecinin farklı aşamalarına özel görevler ekleyebilirsiniz. Örneğin, after 'deploy:publishing', 'my_custom_task' gibi bir ifade ile uygulamanız yayınlandıktan sonra özel bir Rake görevi çalıştırabilirsiniz.

Otomatik Ruby On Rails Uygulama Dağıtımları: Capistrano Rehberi