Laravel uygulamanızı yeni oluşturulmuş bir VPS’ye deploy etmek oldukça karmaşık hale gelebilir. Web uygulamanızı çevrimiçi hale getirmenin pek çok yolu bulunuyor ve “mükemmel” bir dağıtım iş akışı oluşturma çabası içindeyken odaklanmakta zorlanabilirsiniz. Ancak, asıl önemli olan, gerçek projelerde güvenilir, tekrarlanabilir ve güvenli bir dağıtım sürecidir. Bu süreç, kod yazmaya odaklanmanıza olanak tanırken, sunuculara manuel değişiklik göndermekten kurtarır.
Bu makalede, minimum ama üretime uygun bir CI/CD yaklaşımını kullanarak Laravel uygulamalarını bir VPS’ye (veya EC2 örneğine) dağıtmak için GitHub Actions ve SSH kullanarak bir yol haritası sunacağım.
⚠️ Amaç, her türlü optimizasyonu kapsamak değil; gerçek müşteri projeleri ve kişisel ürünler için iyi çalışan bir iş akışını sunmaktır.
💡 Henüz VPS’ye geçmediniz mi? Bu kılavuz, tam root ayrıcalıklarına sahip olduğunuz sunucular için otomatik dağıtım üzerine yoğunlaşmaktadır. Eğer Paylaşımlı Hosting (cPanel) ile sınırlıysanız ve SSH erişiminiz yoksa, alternatif kılavuzuma göz atabilirsiniz: 👉 Paylaşımlı Hosting’de Laravel Dağıtımı (SSH Gerekmez)
Kullanılan Stack
Bu kılavuzda aşağıdaki yapılandırmayı esas alıyoruz:
- Ubuntu Server (20.04+)
- Laravel 12 ve PHP 8.3
- Nginx + PHP-FPM
- MySQL
- CI/CD için GitHub Actions
Bu kılavuz, Linux ve Laravel hakkında temel bir bilgiye sahip olduğunuzu varsayıyor.
Adım 1 — Sunucu Gereksinimlerini Kurma
Sunucunuza SSH ile bağlandıktan sonra, root olarak çalışmamanız önerilir. Bunun yerine sudo yetkilerine sahip bir kullanıcıyla çalışmalısınız.
Pek çok sistem bağımlılığı, ilk kurulumdan sonra yeniden yüklenmemeli ve dağıtımlar yalnızca kod güncellemesiyla yapılmalıdır.
# Sistem listesini güncelleyin ve paketleri yükseltin
sudo apt update && sudo apt upgrade -y
# Nginx'i yükleyin
sudo apt install nginx -y
# MySQL Server'i yükleyin
sudo apt install mysql-server -y
# PHP ve gerekli paketleri yükleyin
sudo apt install php-cli php-fpm php-mysql php-xml php-mbstring php-curl unzip -y
# Composer'i yükleyin
sudo curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer
# Node.js ve NPM'i yükleyin
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt install -y nodejs
⚠️ Kurduğunuz PHP sürümünün Laravel sürüm gereksinimlerinize uydurduğunuzdan emin olun. Uyuşmazlıklar, üretim sorunlarının yaygın bir kaynağıdır.
Adım 2 — Nginx’i Laravel için Yapılandırma
Nginx’i current/public dizinine yönlendirecek şekilde yapılandırmalıyız (bunu daha sonra CI/CD pipeline’ımız aracılığıyla oluşturacağız). Yapılandırmaları oluşturalım:
sudo touch /etc/nginx/sites-available/laravel-app
server {
listen 80;
server_name your-domain.com;
# ATOMİK DAĞITIMLAR İÇİN 'current/public' Hedef Alınır
root /var/www/laravel-app/current/public;
add_header X-Frame-Options "SAMEORIGIN";
add_header X-Content-Type-Options "nosniff";
index index.php;
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:/var/run/php/php8.3-fpm.sock;
fastcgi_index index.php;
fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
include fastcgi_params;
}
location ~ /\.(?!well-known).* {
deny all;
}
}
Daha sonra yapılandırmayı etkinleştirip çalıştığını kontrol edelim:
sudo ln -s /etc/nginx/sites-available/laravel-app /etc/nginx/sites-enabled/
sudo unlink /etc/nginx/sites-enabled/default
sudo nginx -t
sudo systemctl restart nginx
⚠️ your-domain.com kısmını gerçek alan adınızla değiştirin.
Adım 3 — MySQL Sunucusu Kurma ve Veritabanı Oluşturma
MySQL güvenlik scriptini çalıştıralım:
# MySQL'i güvenli hale getirin (root parolasını ayarlayın, anonim kullanıcıları kaldırın)
sudo mysql_secure_installation
# MySQL'e giriş yapın
sudo mysql -u root -p
Sonra, uygulama için kullanacağımız veritabanını oluşturalım:
CREATE DATABASE laravel_db;
CREATE USER 'laravel_user'@IDENTIFIED BY ;
GRANT ALL PRIVILEGES ON laravel_db.* TO @;
FLUSH PRIVILEGES;
EXIT;
Veritabanı oluşturulduktan sonra, üretim .env dosyanıza erişim bilgilerini eklemelisiniz.
⚠️ .env dosyası asla Git’e yüklenmez ve yalnızca sunucuda bir kez oluşturulur. CI/CD pipelines bunu asla değiştirmemelidir.
Adım 4 — Sunucuda Uygulamayı Başlatma
Otomasyondan önce, klasör yapısını kurmamız gerekiyor. Günlüklerin ve yüklemelerin dağıtımlar arasında kalıcı olabilmesi için “shared” bir yapı oluşturacağız.
# 1. Ana dizini oluşturun
sudo mkdir -p /var/www/laravel-app
sudo chown -R $USER:www-data /var/www/laravel-app
# 2. Kalıcı klasörleri kurun
cd /var/www/laravel-app
mkdir -p shared/storage/framework/{cache/data,sessions,views}
# 3. .env dosyasını oluşturun
nano shared/.env
# (Üretim ortamını buraya yapıştırın)
# 4. İzinleri bir kez ayarlayın
sudo chown -R $USER:www-data /var/www/laravel-app
sudo chmod -R 775 shared/storage
Adım 5 — GitHub Actions ile CI/CD Stratejisi
Composer ve NPM komutlarını doğrudan sunucuda çalıştırmak yerine, dağıtım iş akışı önce inşa, sonra dağıt stratejisini takip eder:
Niçin CI’de inşa etmek?
- Daha hızlı dağıtımlar
- Daha öngörülebilir sonuçlar
- Daha az üretim bağımlılığı
- Daha kolay hata ayıklama
- Azaltılmış sunucu yükü
Bu yaklaşımda:
- GitHub Actions, PHP ve Node’u yükler
- Composer bağımlılıkları yüklenir
- Önyüz varlıkları derlenir
- Temiz bir sürüm arşivi oluşturulur
- Sürüm sunucuya SSH ile yüklenir
- Yeni bir sürüm dizini oluşturulur
currentbağlantısı atomik olarak güncellenir
Sunucu, istikrarlı bir çalışma ortamı haline gelir, inşa makinesi değil.
Projenizde .github/workflows/deploy.yml dosyasını oluşturun:
name: Laravel'i VPS'ye Dağıt
on:
push:
branches: [ main ]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
# 1️⃣ Kodu Al
- name: Depoyu kontrol et
uses: actions/checkout@v4
# 2️⃣ PHP'yi Ayarla
- name: PHP'yi Ayarla
uses: shivammathur/setup-php@v2
with:
php-version: 8.3
extensions: mbstring, xml, ctype, iconv, intl, pdo_mysql
# 3️⃣ Backend Bağımlılıklarını Kur
- name: Composer bağımlılıklarını yükle
run: |
composer install --no-dev --prefer-dist --optimize-autoloader
# 4️⃣ Önyüz Varlıklarını Kur
- name: Node'u Kur ve Derle
uses: actions/setup-node@v4
with:
node-version: 20
- run: |
npm ci
npm run build
# 5️⃣ Transfer için Dosyaları Hazırla
- name: Uygulamayı Arşivle
run: |
tar --exclude="./storage" \
--exclude="./.git" \
--exclude="./node_modules" \
--exclude="./tests" \
-czf /tmp/release.tar.gz .
# 2. Dosyayı tekrar çalışma alanına geri taşı
mv /tmp/release.tar.gz .
# 6️⃣ Sunucuya Yükle
- name: Arşivi SCP ile Yükle
uses: appleboy/scp-action@master
with:
host: ${{ secrets.VPS_HOST }}
username: ${{ secrets.VPS_USERNAME }}
key: ${{ secrets.VPS_SSH_KEY }}
port: ${{ secrets.VPS_PORT || 22 }}
source: "release.tar.gz"
target: "/var/www/laravel-app"
# 7️⃣ Sunucuda Dağıt
- name: Uzaktan SSH Komutları Çalıştır
uses: appleboy/ssh-action@master
with:
host: ${{ secrets.VPS_HOST }}
username: ${{ secrets.VPS_USERNAME }}
key: ${{ secrets.VPS_SSH_KEY }}
port: ${{ secrets.VPS_PORT || 22 }}
script: |
set -e
APP_DIR="/var/www/laravel-app"
RELEASE_ID=$(date +%Y%m%d%H%M%S)
RELEASE_PATH="$APP_DIR/releases/$RELEASE_ID"
# 1. Yeni sürüm dizinini oluştur
mkdir -p $RELEASE_PATH
# 2. Dosyaları çıkar
tar -xzf $APP_DIR/release.tar.gz -C $RELEASE_PATH
rm $APP_DIR/release.tar.gz
# 3. Paylaşılan Kaynakları Bağlayın
ln -sfn $APP_DIR/shared/.env $RELEASE_PATH/.env
ln -sfn $APP_DIR/shared/storage $RELEASE_PATH/storage
# 4. İzinleri ayarlayın
sudo chown -R $USER:www-data $RELEASE_PATH
# Önbellek yazma erişimi sağlamak için grubun yazma izni olduğunu doğrulayın
sudo chmod -R 775 $RELEASE_PATH/bootstrap/cache
# 5. Göçleri çalıştırın ve optimize edin
cd $RELEASE_PATH
php artisan migrate --force
php artisan optimize
# 6. Atomik geçiş (sıfır kesinti)
ln -sfn $RELEASE_PATH $APP_DIR/current
# 7. PHP-FPM'yi yeniden yükleyin (bu sunucu sürümünüzle uyumlu olmalıdır!)
sudo systemctl reload php8.3-fpm
# 8. Önceki sürümleri temizleyin (son 5 tanesini saklayarak)
cd $APP_DIR/releases
ls -t | tail -n +6 | xargs -r rm -rf
echo "🚀 Dağıtım $RELEASE_ID başarılı!"
GitHub deposunda:
- Ayarlar → Gizli ve değişkenler → Eylemler’e gidin
- Bu gizli anahtarları ekleyin:
VPS_HOST: VPS IP adresinizVPS_USERNAME: SSH kullanıcı adıVPS_SSH_KEY: Özel SSH anahtarıVPS_PORT: SSH portu (varsayılan: 22)
Adım 6 — Sürüme Dayalı Dağıtım Akışı
Her dağıtım yeni bir sürüm dizini oluşturur:
/var/www/laravel-app/releases/20260210151258
Paylaşılan dizinler (örneğin, storage ve bootstrap/cache) her sürüme sembolik bağlantı ile eklenir.
Her şey hazır olduğunda:
- Veritabanı göçleri
--forceile çalıştırılır - Önbellekler optimize edilir
currentsembolik bağlantısı yeni sürüme geçilir
⚡ Sembolik bağlantı güncellemesi atomik olduğundan, kullanıcılar sık sık kesinti fark etmez.
Yaygın Sorunların Giderilmesi
500 Internal Server Hatası
En yaygın nedenler şunlardır:
- Yanlış dosya izinleri
- Eksik PHP uzantıları
- Yanlış PHP-FPM soket sürümü
- Kırık sembolik bağlantı yolları
storage/ ve bootstrap/cache/ klasörlerinin yazılabilir olduğunu kontrol edin.
Dağıtım Sonrası Boş Sayfa
Sıklıkla şu nedenlerden kaynaklanır:
- Yanlış Nginx kök yolu
- Eksik
.envdosyası - Uygulama anahtarı oluşturulmamış
Şunları kontrol edin:
APP_ENV=production
APP_DEBUG=false
SSH Eylemi Hataları
Genellikle şu nedenlerden kaynaklanır:
- Yanlış özel anahtar biçimi
- Yanlış SSH kullanıcı adı
- Sunucu güvenlik duvarı kuralları
CI’yi sorun gidermeden önce SSH erişimini manuel olarak test edin.
Son Düşünceler
Bu kurulum, profesyonel ve otomatik bir pipeline sağlar. main dalına itme yaptığınızda, GitHub Actions geri kalanını halleder — testleri çalıştırır, varlıkları inşa eder ve bağlantıları kesmeden canlı siteyi değiştirir.
Mutlu Dağıtımlar! 🚀
🔗 İletişimde Kalın
Daha fazla Laravel öğreticisi, geliştirme ipuçları, dağıtım iş akışları ve gerçek dünya üretim sıkıntılarını çözme konularında beni takip edin.
Bu makaleyi faydalı buldunuz mu?
🙏 Destek göstermek için alkışlayın 👏, abone olun 🔔, sosyal medyada paylaşın
Etiketler: Laravel, VPS, GitHub Actions, CI/CD, Nginx
Kaynak: Orijinal Makale
- Kullanılan Stack
- Adım 1 — Sunucu Gereksinimlerini Kurma
- Adım 2 — Nginx’i Laravel için Yapılandırma
- Adım 3 — MySQL Sunucusu Kurma ve Veritabanı Oluşturma
- Adım 4 — Sunucuda Uygulamayı Başlatma
- Adım 5 — GitHub Actions ile CI/CD Stratejisi
- Adım 6 — Sürüme Dayalı Dağıtım Akışı
- Yaygın Sorunların Giderilmesi
- Son Düşünceler
- 🔗 İletişimde Kalın


