Filament Mastery Başlangıçlarına Tam Docker Kurulumu Ekleme

Başlangıç kitlerimde Docker yapılandırması bulunmuyordu. Temel yapı, kimlik doğrulama, roller, MFA, Horizon ve Log Viewer ile sağlamdı; ancak dağıtım kısmı projeyi klonlayan kişinin sorumluluğuna bırakılmıştı.

Bu ilk başta kasıtlı bir tercihti. Docker kurulumları altyapıya bağlı olarak çok farklılık gösteriyor: bazıları ters proxy kullanıyor, bazıları Cloudflare arkasında, bazıları bare metal üstünde, bazıları ise yönetilen platformlarda çalıştırıyor. Hemen sökülmesi gereken bir şey göndermek istemiyordum.

Ancak zamanla fikrimi değiştirdim. İşte bunun sebepleri ve sürecin bana öğrettikleri.

“Kendin yapılandır” meselesi

Bir başlangıç kitinden dağıtımı hariç tutmak mantıklı görünebilir. Ancak pratikte, her proje aynı 4-6 saatlik Docker çalışmasıyla başlıyor ki bu hiç değişmiyor.

Multi-stage Dockerfile. PHP-FPM yapılandırması. HTTPS ile Nginx. PostgreSQL ve Redis ile bağlantı. Horizon ve zamanlayıcının uygun servisler olarak çalışması. Docker’ın her şeyin gerçekten hazır olduğunu bilmesi için sağlık kontrolleri.

Hiçbiri o kadar karmaşık değil. Ama zaman alıcı, ince hatalar yapılması kolay ve projeler arasında neredeyse aynı.

Bir kez bunu kabul ettiğimde, sorunun Docker’ı dahil edip etmemek değil, üretim altyapısı konusunda çok da görüşlü olmadan nasıl etkili bir şekilde dahil edeceğiydi.

Ne inşa ettim?

Oluşumum, yerel geliştirme yığını tamamen kapsıyor:

• multi-stage Dockerfile: Composer bağımlılıkları, Node varlıkları ve nihai PHP-FPM resmi için ayrı aşamalar. Üretim görüntüsünü hafif tutuyor.
• Nginx HTTP-HTTPS yönlendirmesi ve yerel geliştirme için kendinden imzalı sertifika ile birlikte geliyor, yapılandırma gerekmiyor.
• PostgreSQL ve Redis düzgün sağlık kontrolleri ile servisler olarak.
• Horizon ve zamanlayıcı ana uygulama konteynerine yerleştirilmeyen özel servisler olarak.
• A bootstrap servisi uygulama başlamadan önce php artisan migrate --force komutunu çalıştırıyor.

Dockerfile, nihai görüntüyü mümkün olduğunca hafif tutmak için üç aşama kullanıyor:

FROM php:8.4-fpm-alpine AS composer_builder
# Ekleri yükle, composer install çalıştır
# ...

FROM node:24-alpine AS node_builder
# npm bağımlılıklarını yükle, Vite varlıklarını oluştur
# ...

FROM php:8.4-fpm-alpine AS php_fpm
# Nihai görüntü, çalıştırmak için gereken her şeyi içeriyor
# composer_builder'dan vendor/ kopyala
# node_builder'dan public/build/ kopyala
# ...

Her aşama bir işi yapar. Nihai görüntü, Composer, Node veya geliştirme bağımlılıklarını içermez.

Eklemeler, kök olmayan kullanıcı, yerel geliştirme için Xdebug ile birlikte tam Dockerfile mimarisine burada yer verilmektedir: Production-Ready Docker Setup for Laravel Filament.

Bootstrap servisi

Dağıtım sırasında migrate işlemlerini çalıştırmak, uygulama veritabanı hazır olmadan başlatıldığında hata aldıysanız basit bir işlem gibi görünebilir.

Kullandığım model, migrate işlemleri başarıyla tamamlandığında çıkan özel bir bootstrap servisidir. app servisi buna bağımlıdır, böylece uygulama migrate işlemleri tamamlanmadan başlamaz.

bootstrap:
  image: ${APP_IMAGE}:${APP_VERSION}
  command: php artisan migrate --force
  depends_on:
    db:
      condition: service_healthy
    # ...

app:
  image: ${APP_IMAGE}:${APP_VERSION}
  depends_on:
    bootstrap:
      condition: service_completed_successfully
    # ...

horizon:
  image: ${APP_IMAGE}:${APP_VERSION}
  command: php artisan horizon
  depends_on:
    bootstrap:
      condition: service_completed_successfully
    # ...

scheduler:
  image: ${APP_IMAGE}:${APP_VERSION}
  command: php artisan schedule:work
  # ...

SSH yok. Manuel komut yok. “Migrasyonları biri yaptı mı?” sorusu yok.

Bu model hakkında dürüst bir yorum: Tekil dağıtımlar için iyi çalışıyor, bir VPS, bir uygulama konteyneri. Eğer birden fazla replikaya sahipseniz ya da katı sıfır kesintisiz garantileri gerekiyorsa, bu yaklaşımın sınırlamaları var. Aynı anda birden fazla bootstrap servisi çalışabilir ve çelişkiler yaratabilir, uygulama güncelleme sırasında kısaca kullanılamaz hale gelebilir. Böyle bir durumda, migrations’lar CI/CD hattında, konteynerler dağıtılmadan önce işlenmelidir. Bu, ayrı bir makale konusu ve planlarımızda var.

Tam compose kurulumu, hacimler, sağlık kontrolleri, ağ yapılandırması, yeniden başlatma politikaları burada ayrıntılı olarak ele alınmaktadır: Production-Ready Docker Compose for Laravel Filament.

Bilerek dışladıklarım

Üretim için uygun bir Nginx yapılandırmasını dahil etmedim. Zor olduğu için değil, çünkü üretim ortamları çok değişiyor.

Bazı projeler Traefik arkasında. Diğerleri Cloudflare kullanıyor. Kimileri dışarıda yönetilen gerçek Let’s Encrypt sertifikalarına sahipken, bazıları iç PKI kullanıyor. “Üretim” için Nginx yapılandırmasını hepsine uyacak şekilde göndermek yararsız olurdu, çünkü bir yapılandırma diğeri için sessizce kırılabilir.

Gözden geçirdiğim şey, etiketli bir docker-compose.example.yaml göndermektir; bu, başlangıç noktası olarak belirtilir, takviminde bir çözüm değildir. Geliştirici tarafından uyarlanacak şekilde, belgelenmiş, yorumlanmış üretim tarafı. Geliştiricilere hemen üretken olmalarını sağlayacak kadar bir şey sunmalıyız, ancak kendilerine ait olan kararları almak zorunda bırakmamalıyız.

Bu başlangıçlar için ne değiştirir?

Hem Backend Starter hem de Multipanel Starter artık tam Docker yapılandırmasını içermektedir.

Repo’yu kopyalayın, .env.example dosyasını kopyalayın, uygulama anahtarınızı tanımlayın, ardından docker compose up -d --build çalıştırın, ardından php artisan backend:setup yapın, böylece her şey bir arada kimlik doğrulama, roller, MFA, Horizon ve Log Viewer ile çalışan bir panel alırsınız.

“Docker’ı kendin yapılandır” sürecine kıyasla anlamlı bir iyileşme. Docker karmaşık olduğu için değil, o 4-6 saatlik sürenin projeye aktarılması çok daha mantıklı.

Her iki başlangıç da Filament Mastery üyeliği ile kullanılabilir.

Her zamanki gibi, eğer bir şey beklediğiniz gibi çalışmıyorsa ya da farklı bir yaklaşımda bulunursanız, yorumlarda bana bildirin.