# V1 Müşteri Kurulum Rehberi (Customer Installation Guide) Bu doküman, yeni e-ticaret sisteminin canlı (production) veya test sunucularına sıfırdan kurulumunu adım adım açıklamaktadır. Kurulumu gerçekleştirecek teknik ekibin veya müşterinin bu rehberi sırasıyla uygulaması gerekir. --- ## 1. Sunucu Gereksinimleri Sistemin kararlı ve yüksek performanslı çalışabilmesi için aşağıdaki sunucu gereksinimlerinin karşılanması zorunludur: * **İşletim Sistemi:** Linux (Ubuntu 20.04+, Debian, AlmaLinux veya CentOS önerilir) veya uyumlu paylaşımlı hosting. * **Web Sunucusu:** Apache, Nginx veya LiteSpeed (Nginx önerilir). * **Veritabanı Sunucusu:** MySQL 8.0+ veya MariaDB 10.5+. * **SSL Sertifikası:** HTTPS protokolü üzerinden güvenli haberleşme (API'ler, ödeme geçitleri ve lisans kontrolü için zorunludur). * **SSH Erişimi & Composer:** (Yöntem A paketi ile kurulum yapılacaksa gereklidir). --- ## 2. PHP Gereksinimleri & PHP Extension Listesi Uygulama, PHP'nin modern özelliklerini ve güvenlik standartlarını kullanır. * **PHP Sürümü:** **PHP 8.2 veya üzeri** (PHP 8.3 önerilir). ### Zorunlu PHP Eklentileri (Extensions): Aşağıdaki eklentilerin sunucu üzerinde aktif olduğundan emin olunmalıdır: * `pdo` & `pdo_mysql` (Veritabanı bağlantısı için) * `openssl` (Güvenli şifreleme ve imza doğrulama için) * `mbstring` (Çoklu bayt karakter desteği için) * `tokenizer` & `xml` & `ctype` & `json` (Laravel çekirdeği için) * `curl` (Lisans sunucusu ve ödeme API entegrasyonları için) * `gd` veya `imagick` (Ürün resimlerini yeniden boyutlandırma ve galeri yönetimi için) * `zip` (Yedekleme ve güncelleme işlemleri için) * `fileinfo` (Yüklenen medya dosyalarının MIME tiplerini güvenli doğrulamak için) --- ## 3. Web Root / Document Root Ayarı Güvenlik nedeniyle, web sunucusunun public erişim kök dizini (Web Root) uygulamanın ana dizini değil, mutlaka **`public/`** alt dizini olarak ayarlanmalıdır. * **Örnek Doğru Yapılandırma:** `/home/user/domains/example.com/public_html/public` * **Nginx Sunucu Bloğu Örneği:** ```nginx root /var/www/yeni_eticaret/public; index index.php index.html; ``` ### Paylaşımlı Hosting (Shared Hosting) İçin Alternatif Yöntem: Eğer paylaşımlı hosting panelinizde Document Root'u `public/` olarak ayarlamanıza izin verilmiyorsa, aşağıdaki adımlarla kurulum yapabilirsiniz: 1. Proje kök dizinindeki tüm ana dosyaları ve klasörleri (`app/`, `bootstrap/`, `config/`, `vendor/` vb.) web üzerinden erişilemeyen bir üst dizine (örneğin `/home/kullanici/yeni_eticaret/`) yükleyin. 2. Sadece `public/` klasörünün içindekileri web kök dizinine (örneğin `/home/kullanici/public_html/`) taşıyın. 3. Web kök dizinine taşıdığınız `index.php` dosyasını açıp, üst dizindeki Laravel çekirdeğine giden yolları (`autoload.php` ve `app.php` yollarını) güncelleyin. 4. **Hayati Uyarı:** `.env` dosyası kesinlikle doğrudan web üzerinden erişilebilir (`public_html` altında) olmamalıdır. Aksi halde tüm şifreleriniz ve lisans anahtarınız çalınabilir. --- ## 4. Dosyaların Sunucuya Yüklenmesi 1. Hazırlanan V1 teslim paketini (ZIP formatında) sunucunuza yükleyin. 2. Dosyaları web kök dizinine veya belirlediğiniz dizine çıkartın. 3. Dosya izinlerini (Permission) Laravel standartlarına uygun olarak güncelleyin: * `storage/` ve `bootstrap/cache/` klasörleri ile alt klasörlerine web sunucusu yazma yetkisi verilmelidir: ```bash chmod -R 775 storage bootstrap/cache chown -R www-data:www-data storage bootstrap/cache (Ubuntu/Nginx için) ``` --- ## 5. .env Hazırlığı 1. Proje ana dizininde bulunan `.env.example` veya `.env.production.example` dosyasının bir kopyasını oluşturarak adını **`.env`** yapın. 2. `.env` dosyasını düzenleyerek şu temel ayarları girin: * `APP_NAME` (Sitenizin Adı) * `APP_ENV=production` * `APP_DEBUG=false` * `APP_URL` (Sitenizin tam HTTPS adresi, örn: `https://www.example.com`) 3. `DB_` ile başlayan veritabanı bağlantı alanlarını şimdilik boş bırakabilir veya hazırladığınız veritabanı bilgilerini girebilirsiniz (Kurulum Sihirbazı bu alanları otomatik doldurabilir). 4. `LICENSE_SERVER_URL` ve lisans doğrulama bilgilerinin doğruluğunu teyit edin (Geliştirici tarafından verilen varsayılan lisans ayarları kalabilir). --- ## 6. Installer (Kurulum Sihirbazı) ile Kurulum Tarayıcınızı açıp sitenizin adresine (`https://www.example.com`) gittiğinizde sistem henüz kurulmadığı için otomatik olarak **Kurulum Sihirbazı** (`install.php`) devreye girecektir. ### Kurulum Adımları: 1. **Gereksinim Kontrolü:** Sihirbaz, PHP sürümünüzü ve gerekli eklentileri (PDO, GD, vb.) denetler. Eksik eklenti varsa kurulumu durdurur. 2. **Veritabanı Bağlantısı:** * Veritabanı Sunucusu (genelde `127.0.0.1` veya `localhost`), Veritabanı Adı, Kullanıcı Adı ve Şifre bilgilerini girin. * "Bağlantıyı Test Et" butonuyla bilgilerin doğruluğunu teyit edin. Sihirbaz veritabanına bağlanamazsa sonraki adıma geçmenize izin vermez. 3. **Migration & Şema Kurulumu:** * Veritabanı tablolarını ve varsayılan sistem ayarlarını oluşturmak için "Veritabanını Kur" butonuna basın. Arka planda `php artisan migrate --force` komutu çalıştırılacaktır. 4. **İlk Admin (Süper Admin) Oluşturma:** * Yönetim paneline giriş yapabilmeniz için ilk Süper Yönetici hesabını (Ad Soyad, E-posta ve şifre) oluşturun. 5. **Lisans Aktivasyonu:** * Size tanımlanan **Lisans Anahtarını** ilgili alana girin. Sistem otomatik olarak merkezi lisans sunucusuyla iletişim kurarak lisansı doğrulayacak ve Pro özellikleri aktif edecektir. 6. **Storage Link Oluşturma:** * Ürün resimlerinin arayüzde görünebilmesi için sembolik link (`public/storage` -> `storage/app/public`) sihirbaz tarafından oluşturulur. 7. **Kurulumu Tamamlama:** * Kurulum bittiğinde sistem otomatik olarak `storage/app/installed.lock` dosyasını oluşturur. Bu kilit dosyası oluştuktan sonra kurulum sihirbazı dışarıdan erişime tamamen kapanır. --- ## 7. Cron / Scheduler Ayarı Sistemdeki sipariş durumlarının takibi, lisans periyodik kontrolleri, e-posta gönderimleri ve sistem temizliği gibi zamanlanmış görevlerin çalışabilmesi için sunucuda **Cron** tanımı yapılmalıdır. 1. Sunucu terminalinde `crontab -e` komutunu çalıştırın. 2. Aşağıdaki satırı ekleyin (dosya yollarını kendi sunucunuza göre güncelleyin): ```cron * * * * * php /path/to/project/artisan schedule:run >> /dev/null 2>&1 ``` --- ## 8. Queue Worker (Kuyruk Yöneticisi) Ayarı E-posta gönderimi ve sipariş faturalandırılması gibi işlemlerin kullanıcıyı bekletmeden arka planda asenkron çalışması için kuyruk sistemi aktiftir. 1. Arka planda işlerin işlenmesi için şu komutu çalıştırın: ```bash php artisan queue:work --sleep=3 --tries=3 --timeout=90 ``` 2. Bu işlemin sunucu kapansa bile sürekli çalışır durumda kalması için sunucuda **Supervisor** servisini kurmanız önerilir. ### Örnek Supervisor Konfigürasyonu (`/etc/supervisor/conf.d/yeni-eticaret.conf`): ```ini [program:yeni-eticaret-worker] process_name=%(program_name)s_%(process_num)02d command=php /var/www/yeni_eticaret/artisan queue:work --sleep=3 --tries=3 --timeout=90 autostart=true autorestart=true user=www-data numprocs=2 redirect_stderr=true stdout_logfile=/var/www/yeni_eticaret/storage/logs/worker.log ``` --- ## 9. Sistem Ayarları (Kurulum Sonrası Yapılması Gerekenler) ### Mail Ayarları: Yönetici paneline giriş yapın. **Ayarlar -> E-Posta Ayarları** menüsünden SMTP bilgilerinizi (Sunucu, Port, Kullanıcı Adı, Şifre ve Şifreleme Tipi) girip kaydedin. Bir adet test e-postası göndererek çalıştığını doğrulayın. ### Öme Ayarları: **Ayarlar -> Ödeme Yöntemleri** menüsünden anlaşmalı olduğunuz ödeme kuruluşu (örn: iyzico, Paytr) API anahtarlarını girin. Güvenlik için test modunda deneme siparişi verip ardından canlı moda geçiş yapın. ### Kargo Ayarları: **Ayarlar -> Kargo Firmaları** menüsünden kargo fiyatlandırma politikalarını, ücretsiz kargo limitlerini ve API entegrasyonu bilgilerini tanımlayın. --- ## 10. Güvenlik Kontrolleri Kurulum tamamlandıktan sonra aşağıdaki kritik güvenlik adımlarını mutlaka kontrol edin: * [ ] `.env` dosyasında `APP_DEBUG=false` ve `APP_ENV=production` olduğunu doğrulayın. * [ ] Proje ana dizininde `.env` dosyasının web üzerinden doğrudan erişilemediğini (HTTP 403 veya 404 döndüğünü) tarayıcıdan test edin. * [ ] `storage/app/installed.lock` dosyasının oluştuğunu ve `/install` adresine gidildiğinde kurulum sihirbazının tekrar açılmayıp ana sayfaya yönlendirdiğini doğrulayın. * [ ] `.env` dosyasındaki `LICENSE_RESPONSE_SECRET` değerinin lokal geliştirme değeri olmadığını, güçlü ve benzersiz bir random string olduğunu teyit edin. * [ ] Sistem yedekleme veya log dosyalarının `public/` klasörü altında açıkta barındırılmadığından emin olun. --- ## 11. Sık Karşılaşılan Sorunlar (Troubleshooting) #### 1. Sayfa Açıldığında 500 Internal Server Error Veriyor * **Çözüm:** `storage/logs/laravel.log` dosyasını inceleyin. Genellikle `storage/` veya `bootstrap/cache/` klasörlerinin yazma izinlerinin (chmod/chown) eksik olmasından kaynaklanır. #### 2. Görseller Yükleniyor Ama Sitede Kırık/Boş Görünüyor * **Çözüm:** Sembolik link oluşturulamamıştır. SSH üzerinden `php artisan storage:link` komutunu el ile çalıştırın. #### 3. Lisans Doğrulama Başarısız Hatası (License Validation Failed) * **Çözüm:** Sunucunuzun dış dünyaya HTTPS bağlantısı yapabildiğinden ve curl eklentisinin kurulu olduğundan emin olun. Ayrıca `.env` içindeki `LICENSE_SERVER_URL` adresinin erişilebilir olduğunu kontrol edin. --- ## 12. Destek İçin Gerekli Bilgiler Destek talebi oluştururken hızlı çözüm için aşağıdaki bilgileri hazır bulundurun: 1. Sunucu PHP Sürümü ve İşletim Sistemi bilgisi. 2. `storage/logs/laravel.log` dosyasındaki hata çıktıları. 3. Kullandığınız aktif PHP Extension listesi. 4. Lisans anahtarınızın son 4 hanesi.