Yeni bir VPS’ye Laravel uygulamasını deploy etmek karmaşık hale gelebilir. Bir web uygulamasını çevrimiçi hale getirmenin birçok yolu vardır ve “mükemmel” bir deployment akışı oluşturma çabası içinde odak kaybetmek kolaydır. Projelerinizde önemli olan, kod yazmaya odaklanmanıza olanak tanıyan güvenilir, tekrarlanabilir ve güvenli bir deployment sürecidir.
Bu makalede, Laravel uygulamalarını bir VPS’ye (veya EC2 örneğine) deploy etmek için minimum ama üretim hazır bir CI/CD yaklaşımını GitHub Actions ve SSH kullanarak inceleyeceğiz.
⚠️ Hedef, her olası optimizasyonu kapsamaktan ziyade, gerçek müşteri projeleri ve kişisel ürünler için iyi çalışan bir iş akışı sunmaktır.
💡 VPS’niz yok mu? Bu kılavuz, tam root ayrıcalıklarına sahip sunucularda otomatik deploy üzerine odaklanmaktadır. Eğer Shared Hosting (cPanel) ile sıkıştıysanız ve SSH erişiminiz yoksa alternatif kılavuzuma göz atmanızı öneririm: 👉 How to Deploy Laravel on Shared Hosting (No SSH Required)
Kullanılan Teknoloji Yığını
Kullanılan Teknoloji Yığını
Bu kılavuz aşağıdaki kurulumun var olduğunu varsayıyor:
- 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 konusunda temel bir bilgiye sahip olduğunuzu varsayıyor.
Adım 1 — Sunucu Gereksinimlerini Yükleme
Adım 1 — Sunucu Gereksinimlerini Yükleme
Sunucunuza SSH ile bağlandıktan sonra, root olarak çalışmamanız önerilir, bunun yerine sudo ayrıcalıklarına sahip bir kullanıcı olarak çalışmalısınız.
Buradaki ana fikir, bu kurulumu bir kez yapmaktır. İlk sunucu hazırlığı yapıldığında, deployments’ın sistem bağımlılıklarını yeniden yüklemesi gerekmemelidir.
# 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 Sunucusunu 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'ı yükleyin
sudo curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer
# Node.js ve NPM'yi yükleyin
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt install -y nodejs
⚠️ PHP sürümünün Laravel sürüm gereksinimlerinize uyduğundan emin olun. Buradaki uyumsuzluklar, üretim sorunlarının yaygın bir kaynağıdır.
Adım 2 — Laravel için Nginx’i Yapılandırma
Adım 2 — Laravel için Nginx’i Yapılandırma
Nginx’in şu anki current/public dizinine yönlendirilmesi gerekiyor (bunu ileride CI/CD pipeline’ımız ile oluşturacağız). Yapılandırmalara başlayalım:
sudo touch /etc/nginx/sites-available/laravel-app
server {
listen 80;
server_name your-domain.com;
# ATOMIK DEPLOYMENT İÇİN 'current/public' DİZİNİNE YÖNLENDİRİN
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ştiriyoruz ve çalıştığından emin oluyoruz:
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 domaininizle değiştirin.
Adım 3 — MySQL Sunucusunu Kurma ve Veritabanı Oluşturma
Adım 3 — MySQL Sunucusunu Kurma ve Veritabanı Oluşturma
MySQL güvenlik scriptini çalıştıralım:
# MySQL'i güvence altına alın (root şifresini ayarlayın, anonim kullanıcıları kaldırın)
sudo mysql_secure_installation
# MySQL'e giriş yapın
sudo mysql -u root -p
Ardından, uygulama için kullanacağımız veritabanını oluşturalım:
CREATE DATABASE laravel_db;
CREATE USER 'laravel_user'@'localhost' IDENTIFIED BY ;
GRANT ALL PRIVILEGES ON .* TO @;
FLUSH PRIVILEGES;
EXIT;
Oluşturduktan sonra, üretim .env dosyasında veritabanı erişim bilgilerini eklemeliyiz.
⚠️ .env dosyası asla Git’e eklenmemelidir ve sadece sunucuda bir kez oluşturulmalıdır. CI/CD makineleri bunu asla değiştirmemelidir.
Adım 4 — Sunucuda Uygulamayı Başlatma
Adım 4 — Sunucuda Uygulamayı Başlatma
Otomasyondan önce, dosya yapısını kurmamız gerekiyor. Her deployment’ta günlüklerin ve yüklemelerin birikmesi 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ı dizinleri ayarlayın
cd /var/www/laravel-app
mkdir -p shared/storage/framework/{cache/data,sessions,views}
# 3. .env dosyasını oluşturun
nano shared/.env
# (Üretim env içeriğinizi buraya yapıştırın)
# 4. İzinleri BİR KEZ AYARLAYIN
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
Adım 5 — GitHub Actions ile CI/CD Stratejisi
Composer ve NPM komutlarını doğrudan sunucuda çalıştırmak yerine, deployment iş akışı build-then-deploy stratejisini takip eder:
Neden CI içinde inşa etmek yerine sunucuda inşa edelim?
Neden CI içinde inşa etmek yerine sunucuda inşa edelim?
- Daha hızlı deployments
- 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 kurar
- Composer bağımlılıkları yüklenir
- Frontend varlıkları oluşturulur
- Temiz bir sürüm nesnesi üretilir
- Nesne SSH üzerinden sunucuya yüklenir
- Yeni bir sürüm dizini oluşturulur
currentsymlink atomik olarak güncellenir
Sunucu, stabil bir çalışma ortamı haline gelir, inşa makinesi değil.
Laravel projenizde .github/workflows/deploy.yml dosyasını oluşturun:
name: Deploy Laravel to VPS
on:
push:
branches: [ main ]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
# 1️⃣ Kodu Kontrol Et
- name: Repository'yi Kontrol Et
uses: actions/checkout@v4
# 2️⃣ PHP Kur
- name: PHP Kur
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ı kur
run: |
composer install --no-dev --prefer-dist --optimize-autoloader
# 4️⃣ Frontend Varlıklarını Oluştur
- name: Node & Kurulum Yap
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. Geri taşıyın
mv /tmp/release.tar.gz .
# 6️⃣ Sunucuya Yükle
- name: Artifact'i 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 Deploy Et
- 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 bir sürüm dizini oluşturun
mkdir -p $RELEASE_PATH
# 2. Dosyaları çıkarın
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
# Cache için grup yazma erişimini sağlayın (web sunucusu bunun üzerine yazabilsin)
sudo chmod -R 775 $RELEASE_PATH/bootstrap/cache
# 5. Migrations'ı çalıştırın ve optimize edin
cd $RELEASE_PATH
php artisan migrate --force
php artisan optimize
# 6. Atomik Değiştirme (Sıfır Kesinti)
ln -sfn $RELEASE_PATH $APP_DIR/current
# 7. PHP-FPM'yi yeniden yükleyin (sunucu sürümünüzle eşleştiğinden emin olun!)
sudo systemctl reload php8.3-fpm
# 8. Eski sürümleri temizleyin (en son 5'i saklayın)
cd $APP_DIR/releases
ls -t | tail -n +6 | xargs -r rm -rf
echo "🚀 Deployment $RELEASE_ID başarılı!"
GitHub deposunda:
- Ayarlar → Secrets and variables → Actions kısmına gidin
- Aşağıdaki gizlilikleri 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üm Tabanlı Deployment Flow
Adım 6 — Sürüm Tabanlı Deployment Flow
Her deployment 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 symlinklenir.
Her şey hazır olduğunda:
- Veritabanı migrations’ları
--forceile çalıştırılır - Cache’ler optimize edilir
currentsymlink’i yeni sürüme değiştirilir
⚡ Symlink güncellemesinin atomik olması nedeniyle, kullanıcılar nadiren kesinti fark eder.
Sık Karşılaşılan Problemleri Çözme
Sık Karşılaşılan Problemleri Çözme
500 Internal Server Error
500 Internal Server Error
Genellikle şu nedenlerle olur:
- Yanlış dosya izinleri
- Eksik PHP uzantıları
- Yanlış PHP-FPM soket sürümü
- Kırık symlink yolları
storage/ ve bootstrap/cache/ dizinlerinin yazılabilir olduğunu kontrol edin.
Deployment Sonrası Boş Sayfa
Deployment Sonrası Boş Sayfa
Genellikle şunlardan kaynaklanır:
- Yanlış Nginx kök yolu
- Eksik
.envdosyası - Uygulama anahtarı oluşturulmamış
Aşağıdakilerin doğru olduğundan emin olun:
APP_ENV=production
APP_DEBUG=false
SSH Eylemi Başarısız
SSH Eylemi Başarısız
Genellikle şu nedenlerden dolayıdır:
- Yanlış özel anahtar formatı
- Yanlış SSH kullanıcı adı
- Sunucu güvenlik duvarı kuralları
CI’yi hata ayıklamadan önce manuel olarak SSH erişimini test edin.
Son Düşünceler
Son Düşünceler
Bu kurulum size profesyonel, otomatik bir pipeline sunar. main dalına itme yaptığınızda, GitHub Actions geri kalanını halleder — testleri çalıştırır, varlıkları oluşturur ve canlı siteyi bağlantıları düşürmeden değiştirebilir.
Hızlı Deploy’lar!
🔗 Bağlantıda Kalın
🔗 Bağlantıda Kalın
Laravel ile ilgili daha fazla ders, geliştirici ipuçları, deployment iş akışları ve gerçek dünya üretim sorunları çözümü için beni takip edin.
Bu makaleyi faydalı buldunuz mu?
🙏 Desteğinizi gösterin, alkışlayın 👏, abone olun 🔔, sosyal medyada paylaşın
Kaynak: Orijinal Makale
- Kullanılan Teknoloji Yığını
- Adım 1 — Sunucu Gereksinimlerini Yükleme
- Adım 2 — Laravel için Nginx’i Yapılandırma
- Adım 3 — MySQL Sunucusunu 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üm Tabanlı Deployment Flow
- Sık Karşılaşılan Problemleri Çözme
- Son Düşünceler
- 🔗 Bağlantıda Kalın


