How to Automatically Deploy Laravel Applications with Deployer on Ubuntu 16.04

Giriş

Laravel uygulamalarını canlı sunuculara manuel olarak dağıtmak (deployment), özellikle büyük ve sık güncellenen projelerde zaman alıcı, hataya açık ve stresli bir süreç olabilir. Dosyaları kopyalamak, Composer bağımlılıklarını kurmak, veritabanı geçişlerini çalıştırmak ve önbellekleri temizlemek gibi adımlar, her seferinde dikkat gerektirir ve bir adımın unutulması bile uygulamanızın çalışmamasına neden olabilir. Otomatik dağıtım araçları tam da bu noktada devreye girerek bu süreci standartlaştırmanıza, hızlandırmanıza ve insan hatalarını minimize etmenize olanak tanır.

Bu rehberde, Laravel uygulamalarınızı Ubuntu 16.04 sunucusuna (eski bir sürüm olsa da, temel adımlar diğer Ubuntu sürümleri için de geçerlidir) Deployer kullanarak nasıl otomatik olarak dağıtacağınızı adım adım öğreneceksiniz. Deployer, PHP tabanlı, SSH üzerinden çalışan ve sıfır kesinti süresiyle (zero-downtime) dağıtım yapabilen güçlü bir araçtır. Bu sayede, uygulamanızın yeni sürümünü yayınlarken kullanıcılarınız herhangi bir kesinti yaşamaz.

Bu kılavuzun sonunda, bir Laravel uygulamasını yerel geliştirme ortamınızdan bir üretim sunucusuna güvenli ve verimli bir şekilde dağıtmak için gerekli tüm bilgi ve becerilere sahip olacaksınız.

Deployer Nedir ve Neden Kullanmalıyız?

Deployer, PHP projeleri için geliştirilmiş, SSH tabanlı, açık kaynaklı bir dağıtım aracıdır. Capistrano gibi Ruby tabanlı araçlardan esinlenerek tasarlanmıştır ve PHP geliştiricileri için tanıdık bir ortam sunar. Temel amacı, bir uygulamanın yeni bir sürümünü bir sunucuya hızlı, güvenli ve otomatik bir şekilde dağıtmaktır.

Deployer’ın Temel Özellikleri ve Avantajları:

Sıfır Kesinti Süresi (Zero-Downtime) Dağıtımlar: Deployer, yeni sürümleri ayrı bir “release” (sürüm) dizinine dağıtır ve tüm işlemler bittikten sonra mevcut sürümün sembolik bağlantısını yeni sürüme yönlendirir. Bu sayede, yeni sürüm tamamen hazır olana kadar eski sürüm çalışmaya devam eder ve geçiş anında herhangi bir kesinti yaşanmaz.
Geri Alma (Rollback) Yeteneği: Bir dağıtım sonrası sorun yaşandığında, tek bir komutla uygulamanızı önceki çalışan sürüme geri alabilirsiniz. Bu, hatalı dağıtımların riskini büyük ölçüde azaltır.
Otomatik Görevler: Git deposundan kodu çekme, Composer bağımlılıklarını kurma, veritabanı geçişlerini çalıştırma, önbellekleri temizleme, sembolik bağlantıları güncelleme gibi yaygın dağıtım görevlerini otomatikleştirir.
Kolay Yapılandırma: Dağıtım adımları ve sunucu ayarları, basit bir PHP dosyası (deploy.php) içinde tanımlanır. Bu, yapılandırmayı okumayı ve değiştirmeyi kolaylaştırır.
Genişletilebilirlik: Kendi özel görevlerinizi tanımlayabilir ve bunları mevcut dağıtım akışına entegre edebilirsiniz. Bu, özel ihtiyaçlarınıza göre dağıtım sürecini uyarlamanıza olanak tanır.
Ortak Dosya ve Dizin Yönetimi: .env dosyası, storage dizini gibi uygulamanın farklı sürümleri arasında paylaşılması gereken dosya ve dizinleri yönetmek için özel mekanizmalar sunar.

Deployer kullanarak, manuel hataları ortadan kaldırır, dağıtım sürelerini kısaltır ve ekibinizin daha çok geliştirme odaklı çalışmasını sağlarsınız. Bu, DevOps süreçlerinizin önemli bir parçası haline gelebilir.

Ön Gereksinimler ve Sunucu Hazırlığı

Otomatik dağıtıma başlamadan önce hem yerel geliştirme ortamınızda hem de hedef Ubuntu 16.04 sunucunuzda bazı ön gereksinimlerin karşılanması ve belirli ayarların yapılması gerekmektedir.

Yerel Geliştirme Ortamı İçin:

PHP ve Composer: Deployer bir PHP aracı olduğu için, yerel makinenizde PHP ve Composer kurulu olmalıdır.
Git: Uygulama kodunuzu bir Git deposunda (GitHub, GitLab, Bitbucket vb.) barındırmalısınız.
SSH İstemcisi: Sunucuya SSH ile bağlanabilmek için bir SSH istemcisi gereklidir.

Üretim Sunucusu (Ubuntu 16.04) İçin:

Sunucuya SSH ile bağlanın ve aşağıdaki adımları izleyerek hazırlıkları yapın:

1. Sistem Güncellemesi ve Temel Araçların Kurulumu

sudo apt update
sudo apt upgrade -y
sudo apt install -y nginx php7.0-fpm php7.0-mysql php7.0-mbstring php7.0-xml php7.0-bcmath php7.0-zip php7.0-curl git composer

Not: Ubuntu 16.04 için varsayılan PHP sürümü 7.0’dır. Daha yeni Laravel sürümleri daha yeni PHP versiyonları gerektirebilir (örn. Laravel 8/9 için PHP 7.3+). Bu durumda PPA (Personal Package Archive) kullanarak PHP’nin daha yeni bir sürümünü kurmanız gerekebilir (örn. sudo add-apt-repository ppa:ondrej/php).

2. Nginx Konfigürasyonu

Laravel uygulamanız için bir Nginx virtual host dosyası oluşturun. Örneğin, /etc/nginx/sites-available/your_app.conf:

server {
    listen 80;
    server_name your_domain.com www.your_domain.com; # Kendi domaininizi yazın
    root /var/www/your_app/current/public; # Deployer'ın sembolik bağlantı yapısı

    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-XSS-Protection "1; mode=block";
    add_header X-Content-Type-Options "nosniff";

    index index.php index.html index.htm;

    charset utf-8;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location = /favicon.ico { access_log off; log_not_found off; }
    location = /robots.txt  { access_log off; log_not_found off; }

    error_page 404 /index.php;

    location ~ \.php$ {
        fastcgi_pass unix:/run/php/php7.0-fpm.sock; # PHP-FPM soket yolunu kontrol edin
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location ~ /\.(?!well-known).* {
        deny all;
    }
}

Bu dosyayı etkinleştirin ve Nginx’i yeniden başlatın:

sudo ln -s /etc/nginx/sites-available/your_app.conf /etc/nginx/sites-enabled/
sudo rm /etc/nginx/sites-enabled/default # Varsayılan Nginx config'ini kaldırın
sudo nginx -t # Konfigürasyon hatası var mı kontrol edin
sudo systemctl restart nginx

3. Dağıtım Kullanıcısı ve SSH Anahtarları

Dağıtım işlemleri için özel bir kullanıcı oluşturmak en iyi güvenlik uygulamasıdır. Bu kullanıcıya sunucunuzda SSH anahtarı ile erişim sağlayacağız.

sudo adduser deployer
sudo usermod -aG www-data deployer # Nginx'in kullandığı grup, dosya izinleri için önemli

Yerel makinenizdeki SSH genel anahtarını (genellikle ~/.ssh/id_rsa.pub) kopyalayın
ve sunucudaki deployer kullanıcısının authorized_keys dosyasına yapıştırın.
sudo su - deployer
mkdir -p ~/.ssh
chmod 700 ~/.ssh
nano ~/.ssh/authorized_keys
Yerel makinenizdeki id_rsa.pub içeriğini buraya yapıştırın.
chmod 600 ~/.ssh/authorized_keys
exit # deployer kullanıcısından çıkın

Yerel makinenizden ssh deployer@your_server_ip komutuyla şifresiz bağlanabildiğinizden emin olun.

4. Uygulama Dizini ve İzinleri

Deployer’ın kullanacağı kök dizini oluşturun ve gerekli izinleri verin:

sudo mkdir -p /var/www/your_app
sudo chown -R deployer:www-data /var/www/your_app
sudo chmod -R 775 /var/www/your_app # Veya daha kısıtlı bir izin, ancak www-data'nın yazma izni olmalı

5. Veritabanı Kurulumu (Örnek: MySQL)

sudo apt install -y mysql-server
sudo mysql_secure_installation # Güvenli kurulum adımlarını takip edin

MySQL'e bağlanıp veritabanı ve kullanıcı oluşturun
sudo mysql -u root -p
CREATE DATABASE your_app_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'your_app_user'@'localhost' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON your_app_db.* TO 'your_app_user'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Artık sunucunuz Deployer ile dağıtıma hazır!

Laravel Projesi ve Deployer Kurulumu

1. Laravel Projenizi Hazırlama

Eğer henüz bir Laravel projeniz yoksa, yeni bir tane oluşturabilir ve Git deposuna yükleyebilirsiniz:

composer create-project --prefer-dist laravel/laravel my-laravel-app
cd my-laravel-app
git init
git add .
git commit -m "Initial Laravel project"
git remote add origin git@github.com:your-username/my-laravel-app.git # Kendi Git URL'nizi girin
git push -u origin master

Mevcut bir projeniz varsa, tüm değişikliklerin Git deposuna işlendiğinden ve master (veya dağıtım yapacağınız dal) dalının güncel olduğundan emin olun.

2. Deployer Kurulumu (Yerel Makine)

Deployer’ı projenizin dev bağımlılığı olarak kurun:

cd my-laravel-app
composer require deployer/deployer --dev

Kurulum tamamlandıktan sonra, Deployer’ı başlatın. Bu, ana yapılandırma dosyası olan deploy.php‘yi oluşturacaktır:

vendor/bin/dep init

Bu komut size birkaç soru soracaktır. Laravel için genellikle “Laravel” tarifini seçmelisiniz. Bu, Laravel’e özgü dağıtım adımlarını otomatik olarak ekleyecektir.

3. `deploy.php` Dosyasını Yapılandırma

deploy.php dosyasını açın ve sunucunuza ve projenize uygun şekilde yapılandırın. İşte temel bir yapılandırma örneği ve açıklamaları:

set('hostname', 'your_server_ip_or_domain')
    ->set('remote_user', 'deployer') // SSH ile bağlanacağımız kullanıcı
    ->set('deploy_path', '/var/www/your_app') // Uygulamanın sunucudaki kök dizini
    ->set('branch', 'master') // Hangi Git dalından dağıtım yapılacağı
    // ->set('labels', ['stage' => 'production']) // Birden fazla ortam için etiketleme
    ->set('php_fpm_socket', 'unix:/run/php/php7.0-fpm.sock'); // PHP-FPM soket yolu (Ubuntu 16.04 için)

// Özel görevler eklemek isterseniz buraya yazabilirsiniz.
// Örneğin, dağıtımdan sonra bir optimizasyon komutu çalıştırma:
// task('deploy:optimize_clear', function () {
//     run('{{bin/php}} {{release_or_current_path}}/artisan optimize:clear');
// });
// after('deploy:update_code', 'deploy:optimize_clear');

// Dağıtım sonrası veritabanı geçişlerini çalıştırmak için Laravel tarifindeki varsayılan görevi etkinleştirme
// (varsayılan olarak zaten eklenmiş olabilir, kontrol edin)
// before('deploy:symlink', 'artisan:migrate');

// Dağıtım sonrası önbellekleri temizlemek için
// after('artisan:migrate', 'artisan:cache:clear');
// after('artisan:cache:clear', 'artisan:config:cache');
// after('artisan:config:cache', 'artisan:route:cache');
// after('artisan:route:cache', 'artisan:view:cache');

// Dağıtım sonrası gereksiz sürümleri temizle
after('deploy:failed', 'deploy:rollback'); // Bir hata durumunda otomatik geri al

4. `.env` Dosyası Yönetimi

.env dosyası hassas bilgiler (veritabanı kimlik bilgileri, API anahtarları vb.) içerir ve Git deposuna asla eklenmemelidir. Deployer, bu dosyayı shared_files listesine eklediğimiz için özel olarak yönetir.

İlk Dağıtımdan Önce Yapılması Gereken:

Sunucuya SSH ile bağlanın (ssh deployer@your_server_ip).
Uygulamanın kök dizinine gidin: cd /var/www/your_app.
shared dizinini oluşturun: mkdir shared.
.env dosyasını oluşturun ve içeriğini doldurun:

cp .env.example shared/.env
nano shared/.env

shared/.env dosyasının içine veritabanı bağlantı bilgilerini, APP_ENV=production, APP_DEBUG=false gibi üretim ortamı ayarlarını ve boş bir APP_KEY değerini girin.

İzinleri ayarlayın: chmod 664 shared/.env

Deployer ilk dağıtımında bu shared/.env dosyasını alıp current/.env olarak sembolik bağ kuracaktır. Ayrıca, Laravel tarifinde genellikle artisan:key:generate görevi bulunur ve bu, eğer APP_KEY boşsa otomatik olarak yeni bir anahtar oluşturur.

Otomatik Dağıtım ve Yönetim

1. İlk Dağıtımınızı Yapma

Tüm hazırlıkları tamamladıktan sonra, yerel makinenizden ilk dağıtımınızı başlatabilirsiniz:

vendor/bin/dep deploy

Deployer, SSH üzerinden sunucunuza bağlanacak ve aşağıdaki adımları sırasıyla gerçekleştirecektir:

deploy:prepare: Dağıtım dizinlerini (releases, shared, current) oluşturur.
deploy:release: Yeni bir sürüm dizini (örn. releases/1) oluşturur.
deploy:update_code: Git deposundan kodu yeni sürüm dizinine çeker.
deploy:vendors: Composer bağımlılıklarını kurar (composer install).
deploy:shared: .env ve storage gibi paylaşımlı dosyaları/dizinleri sembolik olarak bağlar.
deploy:writable: Belirtilen dizinlere yazma izinleri verir.
artisan:storage:link: Laravel’in storage:link komutunu çalıştırır.
artisan:migrate: Veritabanı geçişlerini çalıştırır.
artisan:cache:clear, artisan:config:cache, artisan:route:cache, artisan:view:cache: Laravel önbelleklerini temizler ve optimize eder.
deploy:symlink: current sembolik bağlantısını yeni sürüm dizinine yönlendirir. Bu, uygulamanızın yeni sürümünü etkinleştirir.
deploy:cleanup: Eski sürümleri temizler (varsayılan olarak son 5 sürümü tutar).

Dağıtım başarılı olursa, tarayıcınızdan your_domain.com adresine giderek uygulamanızın çalıştığını görmelisiniz.

2. Sonraki Dağıtımlar

Uygulamanızda değişiklikler yaptığınızda:

Değişiklikleri Git deposuna işleyin ve dağıtım dalına (örn. master) push edin.
Yerel makinenizden tekrar vendor/bin/dep deploy komutunu çalıştırın.

Deployer, aynı adımları tekrarlayacak, ancak bu sefer yeni bir sürüm dizini oluşturacak ve mevcut current sembolik bağlantısını yeni sürüm hazır olduğunda ona yönlendirecektir. Bu sayede sıfır kesinti süresiyle dağıtım gerçekleşir.

3. Geri Alma (Rollback)

Yeni bir dağıtım sonrası uygulamanızda kritik bir hata fark ederseniz, Deployer ile kolayca önceki çalışan sürüme geri dönebilirsiniz:

vendor/bin/dep rollback

Bu komut, current sembolik bağlantısını bir önceki sürüm dizinine yönlendirir ve uygulamanız anında önceki haline döner. Bu işlem de neredeyse sıfır kesinti süresiyle gerçekleşir.

4. Diğer Faydalı Komutlar

vendor/bin/dep status: Sunucudaki dağıtım durumunu, mevcut sürümü ve önceki sürümleri gösterir.
vendor/bin/dep current: Mevcut aktif sürümün tam yolunu gösterir.
vendor/bin/dep cleanup: Manuel olarak eski sürümleri temizler (varsayılan olarak dağıtım sonunda otomatik çalışır).

vendor/bin/dep artisan : Sunucudaki uygulamanız için Laravel Artisan komutlarını çalıştırır. Örneğin:

vendor/bin/dep artisan db:seed # Veritabanını seed etmek için
        vendor/bin/dep artisan queue:restart # Kuyruk işçilerini yeniden başlatmak için

5. Özel Görevler (Custom Tasks)

Deployer’ın varsayılan görevleri dışındaki özel ihtiyaçlarınız için kendi görevlerinizi tanımlayabilirsiniz. Örneğin, bir önbellek temizleme betiği çalıştırmak veya bir bildirim göndermek:

// deploy.php dosyasında
task('my_custom_task', function () {
    // Sunucuda çalışacak komutlar
    run('echo "Özel görev çalışıyor!"');
    run('{{bin/php}} {{release_or_current_path}}/artisan cache:clear');
});

// Bu görevi dağıtım akışında belirli bir noktaya ekleyin
after('deploy:symlink', 'my_custom_task'); // Sembolik bağlantıdan sonra çalıştır

{{bin/php}} ve {{release_or_current_path}} gibi değişkenler, Deployer tarafından otomatik olarak doldurulur.

Sonuç ve Sıkça Sorulan Sorular (SSS)

Bu rehberde, Laravel uygulamalarınızı Deployer kullanarak Ubuntu 16.04 sunucusuna nasıl otomatik olarak dağıtacağınızı adım adım öğrendiniz. Artık manuel dağıtımın getirdiği zorlukları aşarak, daha hızlı, daha güvenli ve hatasız dağıtımlar yapabilirsiniz. Otomatik dağıtım, geliştirme süreçlerinizi hızlandırır, takımınızın verimliliğini artırır ve uygulamanızın sürekli olarak güncel kalmasını sağlar.

Unutmayın, bu rehber Ubuntu 16.04’ü referans alsa da, Deployer’ın temel prensipleri ve yapılandırması diğer Linux dağıtımları ve Ubuntu’nun daha yeni sürümleri için de büyük ölçüde aynıdır. Sadece PHP-FPM soket yolu veya paket isimleri gibi küçük farklılıklar olabilir.

Sıkça Sorulan Sorular (SSS)

S: APP_KEY nasıl ayarlanır?
C: İlk dağıtımdan önce /var/www/your_app/shared/.env dosyasını manuel olarak oluşturup içine APP_KEY= şeklinde boş bir değer ekleyin. Deployer’ın Laravel tarifi, dağıtım sırasında artisan key:generate komutunu otomatik olarak çalıştırarak bu alanı dolduracaktır.

S: storage dizini neden paylaşımlı olmalı?
C: Laravel’in storage dizini, kullanıcı tarafından yüklenen dosyalar, oturumlar, önbellek dosyaları ve loglar gibi uygulamanın çalışması sırasında oluşan dinamik verileri içerir. Bu verilerin her dağıtımda kaybolmaması ve farklı sürümler arasında paylaşılması gerektiği için shared_dirs listesine eklenmelidir.

S: .env dosyası nasıl güvenli tutulur?
C: .env dosyası hassas veriler içerdiği için asla Git deposuna eklenmemelidir. Deployer, bu dosyayı sunucudaki shared dizininde tutarak ve her yeni sürüme sembolik olarak bağlayarak güvenliği sağlar. Ayrıca, sunucudaki dosya izinlerinin (örneğin chmod 600 shared/.env veya chmod 664 shared/.env) doğru ayarlandığından emin olun.

S: Dağıtım hatalarını nasıl gideririm?
C: Deployer, hataları genellikle açıkça belirtir. En yaygın sorunlar şunlardır:

SSH Bağlantı Sorunları: SSH anahtarlarınızın doğru yapılandırıldığından ve deployer kullanıcısının sunucuya şifresiz bağlanabildiğinden emin olun.
Dosya İzinleri: Sunucudaki /var/www/your_app dizininin ve alt dizinlerinin (özellikle storage ve bootstrap/cache) deployer kullanıcısı ve web sunucusu kullanıcısı (www-data) tarafından yazılabilir olduğundan emin olun.
Composer Hataları: Sunucuda gerekli PHP uzantılarının yüklü olduğundan ve Composer’ın güncel olduğundan emin olun.
.env Dosyası Eksikliği: İlk dağıtımdan önce shared/.env dosyasının oluşturulduğundan ve doğru yapılandırıldığından emin olun.

Daha detaylı hata mesajları için vendor/bin/dep deploy -vvv komutunu kullanarak daha fazla detay alabilirsiniz.

S: Hangi PHP versiyonunu kullanmalıyım?
C: Laravel’in her sürümü belirli PHP versiyonlarını gerektirir. Örneğin, Laravel 6 için PHP 7.2+, Laravel 8/9 için PHP 7.3+ veya 7.4+ önerilir. Ubuntu 16.04 varsayılan olarak PHP 7.0 ile gelir. Eğer daha yeni bir Laravel sürümü kullanıyorsanız, ondrej/php PPA’sı gibi bir depodan daha yeni bir PHP sürümünü kurmanız gerekecektir.

S: Ubuntu 16.04 yerine başka bir versiyon kullanabilir miyim?
C: Evet, kesinlikle. Bu rehberdeki adımlar Ubuntu 18.04, 20.04, 22.04 veya diğer Debian tabanlı dağıtımlar için de büyük ölçüde geçerlidir. Sadece PHP ve Nginx kurulum komutlarında veya PHP-FPM soket yollarında küçük farklılıklar olabilir. Örneğin, Ubuntu 20.04’te php7.0-fpm yerine php7.4-fpm kullanmanız gerekebilir.