Coolify üzerinde kendi sunucunuzda barındırabileceğiniz bir yapay zeka ajanı için Traefik yönlendirmesini düzeltme, tünel ile genel dağıtım modları arasında seçim yapma ve mantıklı bir kimlik bilgisi modeli oluşturma.
Yayınlayan: FutureGo Studio
NousResearch'ün Hermes Agent projesini, Coolify ile yönettiğim kendi VPS'imde çalıştırmak istedim. Varsayımım oldukça basitti: "bir docker-compose dosyası var, bunu Coolify'a veririm ve biter." Ama öyle olmadı. Bu yazıda nelerin ters gittiğini ve bunları nasıl çözdüğümü adım adım anlatıyorum; ortaya çıkan betik ve rehber ise github.com/yucel-yilmaz/hermes-agent-coolify-deploy adresinde açık kaynak olarak yer alıyor.
Coolify, bir Docker Compose projesini kendi yapısal varsayımlarıyla dağıtır: Servisleri kendi oluşturduğu bir ağa bağlar, nelerin dışarı açılması gerektiğini Traefik etiketleri (labels) aracılığıyla tespit eder ve ortam değişkenlerinin kendi arayüzünden yönetilmesini bekler.
Hermes Agent'ın upstream compose dosyası ise bağımsız çalışacak şekilde yazılmıştı:
depends_on sıralamasına ve sağlık kontrollerine (healthchecks) dayanıyor.İlk denemede konteynerler sorunsuz çalıştı ancak Traefik bunların hiçbirini göremedi: Dışarıdan bakıldığında site yoktu, içeriden bakıldığında ise her şey "çalışıyor" durumdaydı.
Coolify'da bir servisi dışarı açmanın doğru yolu port bağlamak değil, servise Traefik etiketleri atamak ve onu Coolify'ın proxy ağına bağlamaktır. Compose dosyasındaki temel değişiklik şu şekildedir:
services:
hermes-agent:
# no host port binding: NO "- 8080:8080"
networks:
- coolify
labels:
- traefik.enable=true
- traefik.http.routers.hermes.rule=Host(`hermes.example.dev`)
- traefik.http.services.hermes.loadbalancer.server.port=8080
networks:
coolify:
external: trueBurada iki nokta önem taşıyor:
coolify ağı external: true olmalıdır. Compose'un kendi ağını oluşturmasına izin vermek, servisi Traefik'in erişemeyeceği izole bir adaya yerleştirir.Bir yapay zeka ajanını internete açarken varsayılan ayar "herkes erişebilir" olmamalıdır. Bu doğrultuda iki mod tanımladım:
Tünel modu (Tunnel mode): Servis asla genel bir alan adına bağlanmaz; erişim yalnızca bir SSH tüneli veya VPN üzerinden gerçekleşir. Tek kullanıcı bensem doğru seçim budur; saldırı yüzeyi neredeyse sıfıra iner.
Genel mod (Public mode): Servis, TLS yönetimi Coolify tarafından yapılan gerçek bir alan adının arkasında, Traefik üzerinde yer alır. Bu modda bir kimlik doğrulama katmanı zorunludur; ajanın uç noktasını korumasız bırakmak, VPS'inizi başkasının LLM faturasına dönüştürür.
Yazdığım betik her iki modu da destekliyor ve varsayılan olarak tünel modunu kullanıyor. Güvenli seçeneğin sonradan etkinleştirilen bir şey değil, varsayılan ayar olması gerektiğine inanıyorum.
Upstream yapılandırması API anahtarlarını bir .env dosyasından okur. Coolify ise gizli değişkenleri kendi arayüzü üzerinden tanımlar ve bunları konteynere ortam değişkenleri olarak aktarır. Buradaki tuzak şu: Coolify'ın compose dosyasındaki env_file yönergesini işleme şekli, beklediğiniz dosyayla eşleşmeyebilir.
Çözümüm, env_file bağımlılığını tamamen ortadan kaldırmak ve tüm gizli bilgileri Coolify'ın ortam yönetimine taşımak oldu. Bu sayede şunları elde edersiniz:
Coolify üzerinde bir şeyler dağıtırken benzer bir engelle karşılaşırsanız, ilgili depoda (repo) bir sorun (issue) açmaktan çekinmeyin.