Kamal ile VPS'e Dağıtım Yapma (Kapsamlı Rehber)

Kamal sizin VPS’inizde çalışmaz. Kendi makinenize veya CI çalıştırıcınıza kurduğunuz bir dağıtım aracıdır ve işini yapmak için sunucuya SSH ile bağlanır. Basecamp bunu Rails uygulamalarını Kubernetes olmadan yayına almak için geliştirdi, ancak Docker imajına derlenen her şeyi dağıtır.

Bu ayrım, neyin peşinde olduğunuzu değiştirir. VPS, Kamal’ın hedefidir; yani uygulamanıza, veri tabanlarınıza ve birkaç günlük imaj sürümüne yetecek kadar büyük olmalıdır. Kamal’ın sunucudaki kendi ayak izi sıfırdır.

Kamal Sunucuya Aslında Ne Kurar

kamal setup, SSH ile bağlanır (varsayılan olarak root kullanıcısıyla ve SSH anahtarınızla kimlik doğrulayarak) ve üç adım çalıştırır: Docker yoksa kurar, tanımladığınız aksesuarları başlatır, ardından uygulamayı dağıtır. Sonrasında sunucuda şunlar çalışır durumdadır:

• kamal-proxy — 80 ve 443 numaralı portları üstlenen, Let’s Encrypt sertifikalarını alan ve dağıtım sırasında yeni konteyner hazır olana kadar gelen istekleri bekleten küçük bir HTTP proxy’si.
• Uygulama konteynerleriniz — config/deploy.yml içinde tanımlı her rol için bir grup.
• Aksesuarlar — yapılandırmada listelediğiniz Postgres, Redis veya diğer servisler.

Kamal’ın kendisi bir gem’dir (gem install kamal, bu yazı yazılırken 2.12.0) ve geride hiçbir arka plan servisi bırakmaz.

Ön Koşullar

Başlamadan önce elinizde şunlar olsun:

• Temiz bir Linux kurulumu ve root SSH anahtar erişimi olan bir VPS (Ubuntu 24.04 makul bir varsayılandır)
• Sunucunuzun çekebileceği bir konteyner registry’si — Docker Hub, GitHub Container Registry veya sağlayıcınızınki
• gem install kamal için yerelde Ruby; Ruby yoksa Kamal’ı bir konteyner imajından da çalıştırabilirsiniz, bazı kısıtlarla
• Uygulamanız için çalışan bir Dockerfile

VPS Sağlayıcısı Seçme

Sunucu yalnızca konteyner çalıştırdığı için sağlayıcıları ağ güvenilirliği, disk payı ve bir sunucuyu ne kadar hızlı yeniden kurabildiğiniz üzerinden değerlendirin:

Kapsamlı bir karşılaştırma için VPS karşılaştırma sayfamıza bakın.

Buradaki en kolay başlangıç noktası DigitalOcean’dır, çünkü dokümantasyonu Kamal’ın sizin yerinize yapmadığı sunucu düzeyindeki işleri kapsar: güvenlik duvarı kuralları, takas alanı ve otomatik güvenlik güncellemeleri.

Sunucuyu Hazırlama

1. VPS’i oluşturun: minimal bir Ubuntu 24.04 imajı ve SSH anahtarınız ekli olsun.
2. Root SSH erişiminin çalıştığını doğrulayın, çünkü Kamal varsayılan olarak böyle bağlanır:

ssh root@sunucu-ip-adresiniz

3. Yalnızca gerekeni açın. TLS’i sunucuda kamal-proxy sonlandırdığı için 22, 80 ve 443 yeterlidir:

ufw allow 22,80,443/tcp && ufw enable

Docker’ı kendiniz kurmanıza gerek yok. Docker yoksa Kamal ilk kamal setup sırasında kurar.

Kamal’ı Kurma ve Yapılandırmayı Yazma

Kendi makinenizde, uygulama dizininizin içinde:

gem install kamal
kamal init

kamal init, config/deploy.yml dosyasını oluşturur. Çalışan asgari bir yapılandırmada bir servis adı, bir imaj ve en az bir sunucu bulunmalıdır:

service: myapp
image: registry-kullanici-adiniz/myapp

servers:
  web:
    hosts:
      - 203.0.113.10

registry:
  username: registry-kullanici-adiniz
  password:
    - KAMAL_REGISTRY_PASSWORD

proxy:
  ssl: true
  host: app.example.com

Gizli değerler, Kamal’ın dağıtım anında okuduğu .kamal/secrets dosyasında durur. Kamal önce .kamal/secrets-common, sonra .kamal/secrets dosyasına bakar:

KAMAL_REGISTRY_PASSWORD=$KAMAL_REGISTRY_PASSWORD

Bu dosyayı sürüm kontrolünün dışında tutun ve değeri kabuk ortamınızdan ya da bir parola yöneticisinden alın.

İlk Dağıtımı Çalıştırma

kamal setup

Bu tek komut Docker’ı kurar, aksesuarları başlatır, imajınızı derleyip gönderir ve uygulamayı ayağa kaldırır. Sonraki her dağıtım şudur:

kamal deploy

Sunucuda nelerin çalıştığını görmek için:

kamal app containers

İmaj Nerede Derlenir

Kamal varsayılan olarak yerelde, yani onu çalıştırdığınız makinede derler ve ardından registry’ye gönderir. Sunucu yalnızca çeker. Dizüstü bilgisayarınız arm64 ve VPS amd64 ise ya hedef mimariyi sabitleyin ya da Kamal’ı uzak bir derleyiciye yönlendirin:

builder:
  arch: amd64
  remote: ssh://[email protected]

Öykünme üzerinden çapraz derleme, her dağıtımda fark edilecek kadar yavaştır. VPS sahip olduğunuz tek amd64 makineyse derleyici görevini de üstlenebilir; ancak o zaman onu yalnızca uygulamayı çalıştırmaya değil, bir Docker derlemesine göre boyutlandırın. Bu da genellikle ek RAM için bir üst plana çıkmak demektir.

Diski Boyutlandırma

Kamal, kamal rollback komutunun önceki bir sürümü registry’den yeniden çekmeden başlatabilmesi için eski konteynerleri ve imajları sunucuda tutar. Bunları varsayılan olarak üç gün sonra temizler. Uygulamanızın kendi verisinin yanına yaklaşık üç günlük imaj sürümü ve bunların paylaşılan temel katmanları için pay ayırın.

Günde birkaç kez dağıtılan 1 GB’lık bir imaj, Hetzner’ın 40 GB NVMe’sinde rahatça durur. 25 GB’lık diskteki 3 GB’lık bir imaj ise diski bir hafta içinde doldurur ve dolan disk mevcut dağıtımı değil bir sonrakini bozar. Bu da onu, aciliyet kazanana kadar gözden kaçması kolay bir sorun hâline getirir.

Kesintisiz Geçiş

kamal-proxy, trafiği yeni konteynere ancak o konteyner GET /up isteğine 200 yanıtı verdiğinde taşır. Bundan iki sonuç çıkar:

• Uygulamanızın bir /up uç noktası olmalıdır. Rails bunu hazır sunar; diğer çatılarda genellikle birkaç satır gerekir.
• Uç nokta yalnızca uygulama gerçekten istek karşılayabildiğinde 200 döndürmelidir. Veri tabanı bağlantıları hazır olmadan yanıt verirse kullanıcılar yeni konteynere çok erken düşer.

Sağlık kontrolü hiçbir zaman geçmezse dağıtım zaman aşımına uğrar ve Kamal trafiği eski konteynerde bırakır.

Dağıtımı Güvene Alma

• Kamal SSH’a root olarak bağlanır; bu yüzden parola ile kimlik doğrulamayı tamamen kapatın ve anahtarlara dayanın.
• TLS’i kamal-proxy’ye bırakın. Önüne ikinci bir ters proxy koymak yalnızca sertifika yolunu karmaşıklaştırır.
• 4 GB’lık sunuculara takas alanı ekleyin. Dağıtımlar kısa süreliğine eski ve yeni konteyneri birlikte çalıştırır ve dağıtımın ortasında takasa düşen bir sunucu, sağlık kontrolü zaman aşımını tetikleyecek kadar yavaşlar.
• Registry parolasını, sürüm kontrolüne giren config/deploy.yml yerine .kamal/secrets dosyasında tutun.

Son İpuçları

• Manuel yol çalıştıktan sonra kamal deploy komutunu CI’dan çalıştırın. Yapılandırma aynıdır; yalnızca gizli değerlerin kaynağı değişir.
• Eski imaj hâlâ diskteyken kamal rollback [sürüm] anında çalışır; bu yüzden bir geri alma hedefinin var olduğunu varsaymadan önce kamal app containers çıktısına bakın.
• Aynı sunucuya ikinci bir uygulama dağıtmak Kamal 2’de destekleniyor. kamal-proxy yönlendirmeyi alan adına göre yaptığı için her uygulamanın yalnızca kendi service adına ve proxy.host değerine ihtiyacı olur.

Altta yatan sunucuyu seçme konusunda daha fazlası için VPS karşılaştırma sayfamıza bakın.