# Canlıya Geçiş Kılavuzu (Deployment Checklist) Bu doküman, Ana E-Ticaret Sistemi'nin üretim (production) ortamına güvenli, sorunsuz ve performanslı bir şekilde kurulması, paketlenmesi ve sürdürülmesi için gerekli tüm teknik adımları ve mimari kararları içermektedir. --- ## 1. Deploy Amacı Bu kılavuzun amacı, yerel geliştirme (local) ortamında geliştirilen e-ticaret uygulamasının canlı sunuculara aktarılırken veri güvenliğini korumak, local geliştirme kalıntılarını (örneğin test lisans sunucusunu) dışarıda bırakmak ve sürdürülebilir bir canlıya alım süreci oluşturmaktır. --- ## 2. Deploy Yöntemleri Projenin kurulacağı canlı sunucunun altyapı kısıtlamalarına göre iki farklı deploy yöntemi kullanılabilir: ### Yöntem A: Sunucuda composer/npm Çalıştırılan Git/CI Deploy Kodların versiyon kontrol sistemi (Git) veya CI/CD aracıyla sunucuya çekildiği, bağımlılıkların doğrudan canlı sunucu üzerinde derlendiği yöntemdir. * **Sunucu Gereksinimleri:** SSH erişimi, Git, Composer, Node.js (NPM) kurulu olmalıdır. * **İş Akışı:** 1. Kod tabanı Git deposundan canlı sunucuya çekilir. 2. Sunucuda `composer install --no-dev --optimize-autoloader` çalıştırılır. 3. `npm install` ve `npm run build` çalıştırılarak assetler sunucuda derlenir. ### Yöntem B: Localde Hazırlanmış vendor ve public/build İçeren Zip Deploy Sunucuda Composer veya Node.js/NPM çalıştırma yetkisi olmadığında (örneğin kısıtlı paylaşımlı hosting ortamlarında), tüm bağımlılıkların ve assetlerin localde (veya CI hattında) derlenip sunucuya paket (zip) halinde yüklendiği yöntemdir. * **Sunucu Gereksinimleri:** Sadece FTP/cPanel erişimi ve PHP çalışma ortamı yeterlidir. * **İş Akışı:** 1. Localde `composer install --no-dev --optimize-autoloader` komutuyla sadece gerekli production bağımlılıkları yüklenir. 2. Localde `npm run build` ile frontend assetleri (`public/build`) üretilir. 3. Hariç tutulacak dosyalar (exclude list) ayıklanarak projenin tamamı zip haline getirilir. 4. Zip dosyası sunucuya yüklenir ve web kök dizininde açılır (unzip). --- ## 3. Dahil Edilecek Dosyalar Canlı sunucuda uygulamanın çalışması için deploy paketinde bulunması gereken temel klasör ve dosyalar şunlardır: * `app/` (Uygulama çekirdek kodları) * `bootstrap/` (Laravel bootstrap ve cache yapılandırması) * `config/` (Yapılandırma dosyaları) * `database/` (Veritabanı migration'ları ve seeder'lar) * `public/` (Web root dizini, index.php, assetler ve `public/build` klasörü) * `resources/` (Blade görünüm şablonları ve kaynak dosyaları) * `routes/` (Uygulama yönlendirme tanımları) * `storage/` (Log, cache ve upload klasörleri - boş veya sadece gerekli alt dizin yapısıyla) * `composer.json` ve `composer.lock` * `.env.example` (Canlı ortamda şablon oluşturmak için) --- ## 4. Hariç Tutulacak Dosyalar (Exclude List) Canlı sunucuya **kesinlikle aktarılmaması** gereken dosya ve dizin listesi: * `.git/` ve Git yapılandırma dosyaları * `.env` (Local geliştirme ortamına ait hassas şifreleri barındırır) * `node_modules/` (Local geliştirme paketleri) * `storage/logs/*` (Local ortamda üretilmiş tüm log dosyaları) * `storage/framework/cache/data/*` (Local önbellek kalıntıları) * `storage/framework/sessions/*` (Local oturum dosyaları) * `storage/framework/views/*` (Localde derlenmiş Blade önbellekleri) * `storage/app/backups/*` (Local veritabanı yedekleri) * `storage/app/public/products/*` (Local test resimleri) * `tests/` ve test konfigurasyonları (`phpunit.xml`, `.phpunit.result.cache`) * IDE ve editör dosyaları (`.vscode/`, `.idea/`) * Gereksiz yedek dosyaları (`*.zip`, `*.rar`, `*.bak`) ### Yöntem A ve Yöntem B için Özel Kurallar: * **`package.json`, `package-lock.json`, `vite.config.js`:** * **Yöntem A'da:** Sunucuda derleme yapılacağı için canlı sunucu paketinde **bulunmalıdır**. * **Yöntem B'de:** Derleme localde tamamlandığı için canlı zip paketinde bulunması **zorunlu değildir**. * *Not:* Bu dosyalar kaynak kod reposunda her zaman korunur ancak son kullanıcıya dağıtılacak nihai production zip paketinden çıkartılabilir. * **`vendor/` klasörü:** * **Yöntem A'da:** Canlı pakete dahil edilmez, sunucu tarafında `composer install` komutuyla oluşturulur. * **Yöntem B'de:** Localde `composer install --no-dev --optimize-autoloader` çalıştırıldıktan sonra üretilen `vendor/` klasörü **canlı zip paketine dahil edilmelidir**. * **`public/build/` klasörü:** * Frontend assetleri (CSS/JS) için kritiktir. Yöntem B kullanılıyorsa, bu klasörün zip paketine mutlaka dahil edildiğinden emin olunmalıdır. --- ## 5. lisans_sunucu Exclude Notu > [!WARNING] > Proje kök dizininde yer alan `lisans_sunucu/` klasörü tamamen local geliştirme ve test amaçlı tasarlanmıştır. Bu klasör canlı e-ticaret deploy paketine **kesinlikle dahil edilmemeli** ve exclude listesinde ilk sıraya konmalıdır. Canlı sunucuda lisans kontrolü, epifizajans'ın merkezi canlı lisanslama sunucusu üzerinden yapılacaktır. Canlı kurulum sırasında bu klasöre dokunulmayacak, taşınmayacak ve local test ortamı dışında çalıştırılmayacaktır. --- ## 6. Production .env Checklist Canlı ortamda çalışacak `.env` dosyasında bulunması gereken zorunlu alanlar ve yapılandırma kuralları: ```env # Temel Uygulama Ayarları APP_NAME="E-Ticaret Canlı" APP_ENV=production APP_DEBUG=false APP_URL=https://canli-domaininiz.com # Güvenlik ve Şifreleme (Her projeye özel sıfırdan üretilmeli) APP_KEY=base64_canli_ortama_ozel_uretilen_anahtar # Veritabanı Yapılandırması (Canlı sunucu MySQL bilgileri) DB_CONNECTION=mysql DB_HOST=127.0.0.1 DB_PORT=3306 DB_DATABASE=canli_veritabani_adi DB_USERNAME=canli_veritabani_kullanicisi DB_PASSWORD=canli_veritabani_guclu_sifresi # Sürücüler (Production için veritabanı veya Redis önerilir) CACHE_STORE=database SESSION_DRIVER=database QUEUE_CONNECTION=database # E-Posta Ayarları MAIL_MAILER=smtp MAIL_HOST=smtp.mailtrap.io MAIL_PORT=2525 MAIL_USERNAME=null MAIL_PASSWORD=null MAIL_ENCRYPTION=tls MAIL_FROM_ADDRESS="no-reply@canli-domaininiz.com" MAIL_FROM_NAME="${APP_NAME}" # SMS Servisi Ayarları SMS_PROVIDER=netgsm NETGSM_USER=username NETGSM_PASS=password # Ödeme Entegrasyonu Ayarları PAYTR_MERCHANT_ID=canli_id PAYTR_MERCHANT_KEY=canli_key PAYTR_MERCHANT_SALT=canli_salt IYZICO_API_KEY=canli_key IYZICO_SECRET_KEY=canli_secret IYZICO_BASE_URL=https://api.iyzipay.com # Kargo Ayarları MNG_CARGO_USER=canli_user MNG_CARGO_PASS=canli_pass # Fatura Entegrasyonu Ayarları EFATURA_USER=canli_user EFATURA_PASS=canli_pass # Merkezi Lisanslama Ayarları (Canlı Lisans Sunucusu) LICENSE_SERVER_URL=https://elisans.epifizajans.com LICENSE_CHECK_ENDPOINT=/api/license/check LICENSE_RESPONSE_SECRET=change_this_to_strong_random_secret LICENSE_CACHE_HOURS=24 LICENSE_GRACE_HOURS=72 LICENSE_RESPONSE_SIGNATURE=true ``` --- ## 7. Lisans İstemcisi Production Ayarları * Canlı e-ticaret uygulaması, localdeki `lisans_sunucu` yerine mutlaka gerçek dış sunucu adresine (`https://elisans.epifizajans.com`) bağlanmalıdır. * `LICENSE_SERVER_URL` değeri asla `localhost`, `127.0.0.1` veya `lisans_sunucu/public` olarak bırakılmamalıdır. * Güvenli doğrulama için `LICENSE_RESPONSE_SIGNATURE` değeri mutlaka `true` (aktif) olmalıdır. --- ## 8. LICENSE_RESPONSE_SECRET Güvenliği Lisans güvenliğinin omurgasını oluşturan `LICENSE_RESPONSE_SECRET` yapılandırması için aşağıdaki kurallara kesinlikle uyulmalıdır: * **Local Gizli Anahtarı Kullanmayın:** Local testlerde kullanılan `EPFZLisansSistemi_ETicaret_Sitesi_icin` veya benzeri test anahtarları canlı sunucuda **kesinlikle kullanılmamalıdır**. * **Güçlü ve Benzersiz Değer:** Canlı ortamda bu parametreye **en az 32-64 karakter uzunluğunda**, karmaşık, tahmin edilmesi imkansız random bir şifre atanmalıdır. * **APP_KEY ile Ayrımı:** `LICENSE_RESPONSE_SECRET` ile Laravel'in `APP_KEY` değeri tamamen farklı şeylerdir. Karıştırılmamalıdır. * **Sunucu-İstemci Senkronizasyonu:** Bu gizli anahtar, e-ticaret istemcisinin `.env` dosyasında ne ise, Lisans Sunucusu (`elisans.epifizajans.com`) yönetim panelinde ilgili lisans kaydına tanımlanan şifre ile **birebir aynı olmak zorundadır**. * **Gizlilik:** Bu şifre e-ticaret admin panelinde asla açıkça gösterilmemeli ve sistem log dosyalarına yazdırılmamalıdır. --- ## 9. Document Root / Public Root * **Önerilen Yapılandırma:** Canlı sunucudaki web root (belge kök dizini) doğrudan Laravel'in `/public` klasörünü göstermelidir. * Örnek Apache/Nginx kök dizin ayarı: `/var/www/eticaret/public` * **Güvenlik Nedeni:** Bu ayar sayesinde `.env` dosyası, `vendor/` dizini, `storage/` altındaki gizli dosyalar web erişimine tamamen kapatılır. * **Symlink Gereksinimi:** `storage/app/public` altındaki görsellerin görüntülenebilmesi için `public/storage` kısayolu (symlink) bulunmalıdır. * **Hosting Kısıtlamaları:** Eğer paylaşımlı hostingde root dizin değiştirilemiyorsa, projenin ana dosyaları web dizininin (`public_html`) bir üst katmanına taşınmalı, sadece `/public` içeriği `public_html` içine atılarak `index.php` dosyasındaki autoload yolları güncellenmelidir. `public_html` içine `.env` veya `vendor/` yüklemek çok ciddi bir güvenlik açığıdır. --- ## 10. Composer/NPM/Build Komutları Canlıya geçiş esnasında çalıştırılması gereken bağımlılık ve derleme komutları: * **Composer Bağımlılık Yükleme (Geliştirme paketleri olmadan):** ```bash composer install --no-dev --optimize-autoloader ``` * **Frontend Asset Derleme (Yöntem A için):** ```bash npm install npm run build ``` --- ## 11. Laravel Cache Komutları Performansı maksimuma çıkarmak ve disk okuma yükünü azaltmak için canlıda yapılandırma, yönlendirme ve şablonların önbelleğe alınması gerekir. * **Önbelleğe Alma (Canlıda Çalıştırılmalı):** ```bash php artisan config:cache php artisan route:cache php artisan view:cache php artisan event:cache ``` * **Önbellekleri Temizleme (Hata durumunda veya güncelleme sonrası):** ```bash php artisan optimize:clear ``` --- ## 12. Storage Link Uygulama üzerinden yüklenen ürün, kategori, marka ve kampanya görsellerinin web üzerinden erişilebilir olması için sembolik bağlantı oluşturulmalıdır: ```bash php artisan storage:link ``` *Canlıda `public/storage` dizininin oluştuğu ve `storage/app/public` klasörüne doğru şekilde yönlendiği mutlaka doğrulanmalıdır.* --- ## 13. Dosya İzinleri Linux tabanlı sunucularda güvenli dosya sahipliği ve yetkilendirme komutları: * **Dosya Sahipliğini Ayarlama (Web server kullanıcısı `www-data` varsayılmıştır):** ```bash chown -R www-data:www-data /var/www/eticaret ``` * **Klasör ve Dosya İzinlerini Sıfırlama:** ```bash find /var/www/eticaret -type d -exec chmod 755 {} \; find /var/www/eticaret -type f -exec chmod 644 {} \; ``` * **Yazma Yetkisi Verme (Kritik dizinler):** ```bash chmod -R 775 /var/www/eticaret/storage chmod -R 775 /var/www/eticaret/bootstrap/cache ``` * *Önemli:* Kesinlikle `chmod -R 777` uygulanmamalıdır. Sadece izin sorunları nedeniyle geçici son çare olarak kullanılacaksa, güvenlik riskleri göz önünde bulundurulmalı ve sorun çözüldükten sonra derhal `775`/`755` seviyelerine geri çekilmelidir. --- ## 14. Cron / Scheduler Laravel zamanlanmış görevlerinin (örneğin newsletter mail gönderimleri, sepet kontrolleri) çalışması için sunucuya eklenmesi gereken cron satırı: ```bash * * * * * cd /var/www/eticaret && php artisan schedule:run >> /dev/null 2>&1 ``` --- ## 15. Queue Worker Arka plana atılan işlerin (kuyrukların) işlenmesi için çalıştırılması gereken komut: ```bash php artisan queue:work --sleep=3 --tries=3 --timeout=90 ``` * **Kuyruk Bağlantısı:** Canlı ortamda `.env` dosyasında `QUEUE_CONNECTION=database` veya `redis` seçilmelidir. `sync` seçilirse kuyruk işlemleri senkron çalışacağından dolayı eposta gönderimleri gibi işlemler web sayfasını yavaşlatacaktır. * **Supervisor Kullanımı:** Canlı sunucularda queue komutunun arka planda sürekli ayakta kalması ve çökme durumunda otomatik yeniden başlaması için Supervisor yazılımı kurulmalı ve yapılandırılmalıdır. --- ## 16. Yedekleme (Backup) Canlıya deploy yapmadan önce veya güncelleme esnasında alınması gereken yedekler: 1. **Veritabanı Yedeği:** Canlı MySQL veritabanının dump yedeği alınmalıdır: ```bash mysqldump -u [db_user] -p [db_name] > pre_deploy_backup.sql ``` 2. **Uygulama Dosyaları Yedeği:** Mevcut çalışan dosyaların arşivi oluşturulmalıdır: ```bash tar -czf app_files_backup.tar.gz /var/www/eticaret ``` 3. **Konfigürasyon Yedeği:** Mevcut `.env` dosyası güvenli bir klasöre kopyalanmalıdır. 4. **Kullanıcı Medya Yedekleri:** `storage/app/public` altındaki görsel klasörleri (`products`, `categories` vb.) yedeklenmelidir. --- ## 17. Geri Alma (Rollback) Deploy sırasında veya hemen sonrasında kritik bir hata oluşursa sistemi eski çalışan haline getirme adımları: 1. Yeni yüklenen tüm dosyalar sunucudan silinir. 2. Yedeklenen eski dosyalar (`app_files_backup.tar.gz`) ana dizine tekrar açılır. 3. Veritabanında bir bozulma veya hatalı çalışan veritabanı migration'ı varsa, alınan sql yedeği geri yüklenir: ```bash mysql -u [db_user] -p [db_name] < pre_deploy_backup.sql ``` 4. Eski `.env` dosyası yerine geri konur. 5. Laravel önbellekleri temizlenip yeniden yapılandırılır: ```bash php artisan optimize:clear ``` 6. Arka planda kuyruk çalışıyorsa restart edilir: `php artisan queue:restart` --- ## 18. Installer Mimarisi Aşama 80'de kodlanacak olan kurulum sihirbazının teknik mimarisi **Hibrit Yapı** olarak kurgulanacaktır: * **Birinci Seviye Kontrol (`public/install.php`):** * Laravel framework'ü boot edilmeden önce çalışacak olan saf PHP dosyasıdır. * **Önemli Not:** Eğer `.env` dosyası hiç yoksa veya `APP_KEY` ve veritabanı bağlantı ayarları tam olarak yapılmamışsa Laravel boot etmeye çalışırken PHP fatal hatası fırlatabilir ve yönlendirmeler çalışmayabilir. Bu nedenle `public/install.php` ilk seviye kontrolcü ve yönlendirici olarak kritik bir role sahiptir. * Görevi: Laravel'in düzgünce başlayıp başlayamayacağını denetlemek, sistem gereksinimlerini kontrol etmektir. * Yaptığı Kontroller: * PHP versiyonu (`^8.2`) yeterli mi? * Gerekli PHP extension'ları (PDO, OpenSSL, Mbstring, cURL, GD, XML, Zip) yüklü mü? * `storage/` ve `bootstrap/cache/` klasörleri yazılabilir (writable) mi? * `.env` dosyası mevcut mu? (Yoksa `.env.example` dosyasını kopyalayıp temel yapıyı kurar, `APP_KEY` üretir) * `installed.lock` dosyası mevcut mu? (Varsa kurulumu engeller) * Bu kontroller başarılıysa, kullanıcıyı veritabanı bilgilerini girmesi için asıl Laravel kurulum route'una (`/install`) yönlendirir. * **İkinci Seviye Kurulum (Laravel `/install` Route & Controller):** * Laravel çatısı altında çalışan güvenli yapıdır. * Görevi: Veritabanı tablolarının oluşturulması (migrations), varsayılan verilerin eklenmesi (seeding), ilk süper yönetici (Super Admin) hesabının tanımlanması ve lisans anahtarının doğrulanması adımlarını yönetir. --- ## 19. Installer Güvenliği Kurulum sihirbazının canlı sunucuda bir güvenlik açığı oluşturmaması için şu kurallar uygulanır: * **Kurulum Dosyalarının Paketteki Durumu:** Kurulum dosyaları (hem `install.php` hem de Laravel kurulum yönlendirmeleri) deploy paketine dahil edilecektir ancak kurulum tamamlandığı an otomatik olarak kilitlenecektir. * **Kilit Mekanizması:** Kurulum adımları bittiğinde sistem otomatik olarak `storage/app/installed.lock` dosyasını oluşturacaktır. * **Lock Dosyası Kontrolü:** * `installed.lock` dosyası mevcut olduğu sürece `public/install.php` dosyası hiçbir işlem yapmadan doğrudan sonlandırılmalı (die/exit) veya ana sayfaya yönlendirmelidir. * Laravel tarafındaki `/install` route'ları ve ilgili controller yapıları, bu kilit dosyası varsa `403 Forbidden` hatası vermeli veya ana sayfaya yönlendirme yapmalıdır. * **Güvenlik Riski Uyarısı:** Canlı sunucuda bu kilit mekanizmasının çalışmaması veya `installed.lock` dosyasının silinmesi durumunda, kötü niyetli kişiler kurulum sayfasına tekrar erişerek veritabanını sıfırlayabilir veya kendi admin hesaplarını tanımlayabilir. Bu durum **kritik seviyede bir güvenlik riskidir**. --- ## 20. Deploy Sonrası Test Checklist Uygulama canlıya alındıktan veya kurulum sihirbazı tamamlandıktan sonra test edilmesi gereken kritik adımlar: * [ ] **Erişim Kontrolü:** Ana sayfa, kategoriler ve ürün listeleme sayfaları hatasız açılıyor mu? * [ ] **CSS/JS Yüklenmesi:** Sayfalarda tasarım bozukluğu var mı? (Asset ve `public/build` yollarının kontrolü) * [ ] **Görsellerin Görüntülenmesi:** Ürün, marka ve kategori resimleri düzgün yükleniyor ve görünüyor mu? (`storage:link` kontrolü) * [ ] **Sepet İşlemleri:** Ürün sepete ekleniyor mu, sepet sayfası görüntülenebiliyor mu? * [ ] **Checkout Akışı:** Adres bilgileri girilip ödeme adımına geçilebiliyor ve sipariş başarıyla tamamlanıyor mu? * [ ] **Ödeme Yöntemleri:** PayTR veya iyzico ödeme formları/seçenekleri ödeme ekranında düzgün yükleniyor mu? * [ ] **E-Posta Gönderimi:** Sipariş sonrası müşteriye "Siparişiniz Alındı" e-postası ulaşıyor mu? * [ ] **PDF Fatura/Belge:** Sipariş detayından veya admin panelinden PDF fatura/belge üretimi sorunsuz çalışıyor ve indiriliyor mu? * [ ] **Admin Paneli Girişi:** `/admin` veya belirlenen yönetim paneli yoluna giriş yapılabiliyor mu? * [ ] **Lisans Aktivasyonu:** Admin panelinde lisans sorgulaması başarılı çalışıyor mu ve modüller lisans durumuna göre aktifleşiyor mu? * [ ] **System Health Kontrolü:** Admin panelindeki sistem sağlık paneli herhangi bir hata raporluyor mu? * [ ] **Hata Logları:** `storage/logs/laravel.log` dosyasına yeni bir hata satırı düşmüş mmü? --- ## 21. Canlıya Çıkmadan Önce Son Güvenlik Kontrolleri Uygulamayı halka açmadan önce doğrulanması gereken kritik güvenlik adımları: * [ ] **Hata Ayıklama Kapalı:** `.env` dosyasında `APP_DEBUG=false` olduğundan emin olun. * [ ] **Kilit Dosyası Aktif:** `storage/app/installed.lock` dosyasının başarıyla oluşturulduğunu teyit edin. * [ ] **Geliştirici Logları Temiz:** Log dosyalarında açıkta yazılmış lisans anahtarı, veritabanı şifresi veya API gizli anahtarı (secret) bulunmadığını doğrulayın. * [ ] **Test Verileri Temizlendi:** Localde açılan demo kullanıcılar (`admin@test.com`, `superadmin@test.com` vb.) ve test veritabanı kayıtları tamamen silinmiş veya şifreleri güçlü şifrelerle değiştirilmiş olmalıdır. `admin123` gibi basit şifreler canlıda barındırılmamalıdır. * [ ] **Hassas Klasör Koruması:** `.env` dosyasına veya `vendor/` klasörüne tarayıcıdan doğrudan erişilmeye çalışıldığında sunucunun `403` veya `404` döndürdüğünü doğrulayın. (Document Root `/public` olarak ayarlanmışsa bu otomatik sağlanır). --- ## 22. System Health Paneli ve Sistem Gereksinim Kontrolleri İlişkisi * **Aşama 80 (Installer):** Kurulum sihirbazı esnasında yapılacak gereksinim kontrolleri (PHP sürümü, yazma izinleri ve PHP uzantıları), uygulamanın henüz kurulmadığı ilk aşamada sistemin kurulabilirliğini denetler. * **Canlı Ortam (SystemHealthService):** Canlı sistemde kurulu olan `SystemHealthService` ise, kurulum bittikten sonra uygulamanın çalışma zamanındaki sağlığını (kuyrukların birikmesi, scheduler çalışmaması vb.) takip etmek için kullanılır. * **Çift Kod Yazımının Önlenmesi:** Aynı gereksinim kontrollerini sıfırdan yazarak kod tekrarı oluşturmamak adına; kurulum sonrasındaki tüm canlı denetimler için mevcut `SystemHealthService` yapısı kullanılmalıdır. Installer ise sadece Laravel boot aşamasına kadar olan temel kontrolleri yapacaktır.