Laravel Sail Nedir?
Laravel Sail, Laravel uygulamaları için resmî olarak sunulan, Docker tabanlı bir yerel geliştirme ortamıdır. Amaç, her geliştiricinin makinesinde aynı PHP sürümü, aynı veritabanı sürümü ve aynı servis bileşimini çalıştırmasını sağlamaktır. Sail, docker-compose (Compose V2 ile docker compose) komutlarını saran ince bir kabuktur; arka planda aslında bir Compose dosyası ve servis tanımları vardır.
Sail'in avantajı, PHP, MySQL, Redis gibi bileşenleri ana makineye kurmadan izole bir ortamda çalıştırabilmenizdir. Dezavantajı ise Docker'ın kendisini öğrenmeniz gerekmesidir; Sail sihirli bir kutu değildir.
Önkoşullar
- Docker Desktop (macOS/Windows) veya Docker Engine + Compose eklentisi (Linux)
- Docker'ın çalışır durumda olması
- Yeni bir Laravel projesi kuruyorsanız Composer; mevcut bir projeye Sail ekliyorsanız projenin kök dizini
- Linux'ta kullanıcının
dockergrubunda olması veyasudoyetkisi
Sail, WSL2 üzerinde Windows'ta da çalışır. Windows'ta projeyi WSL dosya sisteminde tutmak dosya erişim performansı açısından genellikle daha iyidir.
Yeni Projede Sail Kurulumu
Yeni bir Laravel projesi oluştururken Sail'i doğrudan dahil edebilirsiniz:
composer create-project laravel/laravel ornek-proje
cd ornek-proje
composer require laravel/sail --dev
php artisan sail:install
sail:install komutu hangi servisleri dahil etmek istediğinizi sorar (MySQL, PostgreSQL, Redis, Mailpit vb.). Seçiminize göre compose.yaml dosyası ve docker/ altındaki yapılandırma dosyaları oluşturulur.
Ardından ortamı başlatın:
./vendor/bin/sail up -d
-d bayrağı konteynerleri arka planda çalıştırır. İlk çalıştırmada imajların indirilmesi ve derlenmesi zaman alabilir.
Mevcut Projeye Sail Ekleme
Elinizde zaten bir Laravel projesi varsa aynı iki komut yeterlidir:
composer require laravel/sail --dev
php artisan sail:install
.env dosyanızı Sail'in beklediği servis adreslerine göre güncellemeniz gerekir. Örneğin veritabanı host'u 127.0.0.1 yerine servis adı olan mysql olmalıdır:
DB_CONNECTION=mysql
DB_HOST=mysql
DB_PORT=3306
DB_DATABASE=laravel
DB_USERNAME=sail
DB_PASSWORD=password
Bu değerler compose.yaml içindeki servis tanımıyla eşleşmelidir. Sail varsayılan olarak sail kullanıcı adı ve password parolasıyla bir MySQL servisi tanımlar; kendi yapılandırmanızı yaptıysanız .env değerlerini ona göre düzeltin.
Günlük Kullanım
./vendor/bin/sail komutunu her seferinde yazmak yerine bir kabuk takma adı tanımlayabilirsiniz:
alias sail='[ -f sail ] && sh sail || sh vendor/bin/sail'
Bu satırı ~/.bashrc veya ~/.zshrc dosyanıza ekleyerek sail komutunu kısaltabilirsiniz. Laravel'in ürettiği projelerde kök dizinde sail adlı bir betik bulunur; takma ad önce onu, yoksa vendor/bin/sail yolunu kullanır.
Sık kullanılan komutlar:
sail up -d # Servisleri arka planda başlat
sail down # Servisleri durdur ve konteynerleri kaldır
sail ps # Çalışan servisleri listele
sail logs # Tüm servislerin loglarını izle
sail artisan migrate # Konteyner içinde artisan çalıştır
sail composer install # Konteyner içinde composer çalıştır
sail npm run dev # Konteyner içinde npm çalıştır
sail php artisan tinker # PHP REPL
sail shell # Konteyner içinde kabuk aç
sail komutundan sonra yazdığınız her şey, uygulama konteynerinin içinde çalıştırılır. Bu sayede ana makinede PHP veya Node kurulu olmasa bile projeyi geliştirebilirsiniz.
Servisleri Genişletme
Varsayılan kurulumda ihtiyacınız olan tüm servisler olmayabilir. compose.yaml dosyasını düzenleyerek yeni servisler ekleyebilir veya mevcut olanları özelleştirebilirsiniz. Örneğin ek bir MySQL servisi tanımlamak için mysql bloğunu çoğaltıp isim ve portları değiştirmeniz yeterlidir.
Yapılandırma değişikliklerinden sonra konteynerleri yeniden oluşturmanız gerekir:
sail down
sail up -d
Sadece sail restart çoğu durumda yeterli olmaz; imaj veya ortam değişkeni değiştiyse sail build --no-cache ile yeniden derlemeniz gerekebilir.
Yaygın Hatalar
Port çakışması. Ana makinede zaten çalışan bir MySQL veya Redis varsa Sail başlatılamaz. compose.yaml içindeki port eşlemesini değiştirin (örneğin 3306:3306 yerine 3307:3306) ve .env dosyasındaki DB_PORT değerini buna göre güncelleyin.
DB_HOST=localhost kullanmak. Konteyner içinden localhost kendi konteynerini işaret eder, veritabanı servisini değil. Servis adını (mysql, pgsql, redis) kullanın.
Dosya izinleri. Linux'ta Sail'in oluşturduğu dosyalar sail kullanıcısına ait olabilir. Proje dosyalarınızı düzenlerken izin sorunları yaşıyorsanız sail kullanıcı kimliğini kendi kullanıcınızla eşleştirmek için ortam değişkenleri tanımlayabilirsiniz; ayrıntılar Laravel dokümantasyonundadır.
sail:install sonrası .env güncellememek. Servis adlarını .env'e yansıtmadığınızda uygulama veritabanına bağlanamaz.
Docker Desktop kapalıyken komut çalıştırmak. sail her komutu Docker üzerinden çalıştırdığı için Docker servisi çalışmıyorsa komutlar hata verir.
Güvenlik Notları
Sail geliştirme ortamı içindir, üretim için değildir. Varsayılan parolalar (password), açık portlar ve hata ayıklama modu üretimde kabul edilemez. compose.yaml ve .env dosyalarını üretim sunucusuna taşımayın.
Portları yalnızca gerektiğinde dışarı açın. Veritabanı ve Redis portlarını ana makineye yayınlamak zorunda değilseniz, compose.yaml içindeki ports satırlarını kaldırın; uygulama konteyneri servislere iç ağ üzerinden erişmeye devam eder.
Projeyi herkese açık bir ağda geliştiriyorsanız Sail'in açtığı portlara güvenlik duvarı kuralı uygulayın. Özellikle 3306, 6379 ve 8025 gibi servis portlarını internete açık bırakmayın.
Ortamı Sıfırlama
Bozulan bir ortamı temizlemek için:
sail down -v
-v bayrağı volume'ları da siler; bu, veritabanı verilerinin kaybolacağı anlamına gelir. Veriyi korumak istiyorsanız -v kullanmayın.
Kapanış
Sail, Laravel projelerinde ortam tutarlılığını sağlamanın pratik bir yoludur. Ancak altında Docker Compose olduğunu unutmayın: sorun çıktığında docker compose logs, docker compose ps ve compose.yaml dosyası ilk başvuracağınız araçlardır. Sail komutlarını ezberlemek yerine Compose'un nasıl çalıştığını anlamak, karşılaşacağınız sorunların çoğunu kendi başınıza çözmenizi sağlar.
