setupsetup-guide

ABS Kurulum Rehberi

Kendi sunucunuzdaki ABS'yi yaklaşık 30 dakikada kurun

Bu rehberle, kendi Linux sunucunuzda tam fonksiyonel bir ABS örneğini ayağa kaldıracaksınız. Başlamadan önce, size gönderdiğimiz hoş geldin e-postasını kontrol edin. Bu e-postada kurulum için gerekli üç dosya ekli: docker-compose.yml, Caddyfile ve .env.template. Lisans anahtarınız ise 24 saat içinde ayrı bir e-posta ile size ulaşacak. Hazırsanız başlayalım.

1. VPS'inizi hazırlayın

ABS için temiz bir Ubuntu 22.04+ sunucu tavsiye ediyoruz. Minimum sistem gereksinimleri 2 vCPU, 4 GB RAM ve 40 GB disk alanıdır. Fiyat/performans oranıyla Hetzner'in CX22 (€3.79/ay) modeli başlangıç için harika bir seçimdir. Sunucuyu hazırladıktan sonra, kullanacağınız bir subdomain (örneğin abs.sirketiniz.com) için bir DNS A kaydı oluşturun ve bunu sunucunuzun public IP adresine yönlendirin. Güvenlik duvarınızda (ufw gibi) SSH (22), HTTP (80) ve HTTPS (443) portlarının açık olduğundan emin olun: sudo ufw allow 22,80,443. Güvenlik için, işlemleri root olmayan, sudo yetkilerine sahip bir kullanıcı ile ve şifre yerine SSH anahtarı kullanarak yapmanızı şiddetle öneririz. Son olarak, .env dosyasında kullanacağımız ABS_PUBLIC_HOSTNAME değişkeninin değerini, az önce oluşturduğunuz bu subdomain olarak belirleyeceksiniz.

# Point an A record at your VPS public IP, then on the server:
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo adduser abs && sudo usermod -aG sudo abs
ssh-copy-id abs@your.hostname.com

2. Docker'ı kurun ve GHCR'a giriş yapın

Sunucunuza Docker ve Docker Compose'u kurmanın en kolay yolu resmi script'i kullanmaktır: curl -fsSL https://get.docker.com -o get-docker.sh && sh get-docker.sh. Kurulumdan sonra, Docker komutlarını sudo olmadan çalıştırabilmek için mevcut kullanıcınızı docker grubuna ekleyin: sudo usermod -aG docker $USER. Bu değişikliğin etkili olması için sunucudan çıkış yapıp tekrar giriş yapmanız gerekir. Her şeyin yolunda olduğunu docker run hello-world komutuyla test edebilirsiniz. ABS imajları özel (private) olduğu için, bunları çekebilmek üzere GitHub Container Registry'ye (GHCR) giriş yapmalısınız. Hoş geldin e-postanızda size özel, salt okunur (read-only) bir Personal Access Token (PAT) bulacaksınız. Bu token'ı kullanarak docker login ghcr.io komutunu çalıştırın. Kullanıcı adı olarak GitHub kullanıcı adınızı, şifre olarak da bu token'ı yapıştırın. Bu token'ı kimseyle paylaşmayın.

curl -fsSL https://get.docker.com -o get-docker.sh
sh get-docker.sh
sudo usermod -aG docker $USER
# log out, log back in
docker run hello-world
docker login ghcr.io   # paste read-only PAT from your welcome email

3. Üç ekli dosyayı kaydedin ve .env'i doldurun

Kurulum dosyalarını düzenli tutmak için sunucunuzda bir dizin oluşturalım: mkdir /opt/abs. Hoş geldin e-postanızdaki üç eki (docker-compose.yml, Caddyfile, .env.template) bu dizine kopyalayın. Şimdi, yapılandırma dosyasını hazırlama zamanı. nano /opt/abs/.env.template komutuyla dosyayı düzenlemeye başlayın. Üç temel değişkeni doldurmanız zorunludur: ABS_LICENSE_KEY (bu, 24 saat içinde size ayrı bir e-postayla gönderilecek olan lisans anahtarınızdır), ABS_PUBLIC_HOSTNAME (1. adımda belirlediğiniz subdomain) ve ABS_ACME_EMAIL (Let's Encrypt'in SSL sertifikası için kullanacağı e-posta adresiniz). Opsiyonel olarak, Anthropic, OpenAI veya Groq gibi LLM sağlayıcılarının API anahtarlarını da ekleyebilirsiniz. Unutmayın, bir API anahtarı eklemezseniz, ABS bu sağlayıcılara hiçbir çağrı yapamaz. Düzenlemeyi bitirdikten sonra dosyayı kaydedin ve adını değiştirin: mv /opt/abs/.env.template /opt/abs/.env.

sudo mkdir -p /opt/abs && sudo chown $USER:$USER /opt/abs
cd /opt/abs
# save docker-compose.yml, Caddyfile, .env.template here
# (download from your welcome email attachments)
nano .env.template   # fill ABS_LICENSE_KEY, ABS_PUBLIC_HOSTNAME, ABS_ACME_EMAIL
mv .env.template .env

4. ABS'yi docker compose ile ayağa kaldır

Artık her şey hazır. /opt/abs dizinindeyken docker compose -f docker-compose.yml up -d komutunu çalıştırarak ABS'yi başlatın. Servislerin ayağa kalkması yaklaşık 60 saniye sürer. Süreci docker compose logs -f komutuyla canlı olarak izleyebilirsiniz. Loglarda backend servisinin health: starting durumundan healthy durumuna geçtiğini göreceksiniz. Bu sırada, caddy servisi Let's Encrypt ile iletişime geçerek ABS_PUBLIC_HOSTNAME için bir TLS sertifikası talep edecektir. Bu işlemin başarılı olması için DNS kaydınızın yayılmış ve 80/443 portlarınızın dışarıya açık olması kritik öneme sahiptir. Her şey yolunda gittiyse, curl https://abs.sirketiniz.com/healthz komutu OK çıktısı vermelidir. Bu, sisteminizin sağlıklı ve erişilebilir olduğunu gösterir.

cd /opt/abs
docker compose -f docker-compose.yml up -d
docker compose logs -f      # wait ~60s for backend healthcheck
curl https://your.hostname.com/healthz

5. İlk-çalıştırma kurulum sihirbazı

Sunucu tarafı hazır olduğuna göre, şimdi kullanıcı arayüzü üzerinden son adımları tamamlayalım. Tarayıcınızı açın ve https:// ile başlayan tam adresinize gidin (örneğin https://abs.sirketiniz.com). Karşınıza ilk kurulum sihirbazı çıkacak. Bu sihirbaz sizden bir yönetici (admin) hesabı için e-posta ve şifre belirlemenizi isteyecektir. Ayrıca, hassas verileri şifrelemek için opsiyonel bir vault key ve daha önce .env dosyasına eklemediyseniz LLM sağlayıcı anahtarlarını girme imkanı sunar. Sihirbaz, .env dosyanıza girdiğiniz lisans JWT'sini doğrulayacak ve bu kurulumu lisansınıza özel bir 'parmak izi' (fingerprint) ile eşleştirecektir. İşlem tamamlandığında, otomatik olarak yönetici paneline yönlendirileceksiniz. Tebrikler, ABS'yi başarıyla kurdunuz!

# Open in your browser:
# https://your.hostname.com
# Wizard:
#   1. Admin email + password
#   2. Optional vault key
#   3. Optional provider keys (Anthropic / OpenAI / Groq / Cohere)
#   4. License JWT validation

Sorun giderme

Kurulum sırasında karşılaşılan sorunların çoğu genellikle DNS, güvenlik duvarı (firewall) yapılandırması veya kimlik doğrulama token'larındaki hatalardan kaynaklanır. İşte en sık rastlananlar ve çözümleri:

GHCR kimlik doğrulama hatası

İmajları çekerken unauthorized veya authentication required hatası alıyorsanız, docker login ghcr.io komutunda kullandığınız PAT (Personal Access Token) geçersiz veya süresi dolmuş olabilir. Hoş geldin e-postasındaki token'ı kopyalayıp komutu tekrar deneyin. Sorun devam ederse, ~/.docker/config.json dosyasını kontrol ederek ghcr.io için doğru kimlik bilgilerinin kaydedildiğinden emin olun.

docker login ghcr.io
cat ~/.docker/config.json | grep ghcr.io

Lisans aktivasyon zaman aşımı

backend servisinin loglarında activation failed veya license activation timeout gibi bir hata görüyorsanız, bunun iki yaygın nedeni vardır: sunucunuzun saatinin senkronize olmaması veya dışarı giden (egress) trafiğin engellenmesi. Saati sudo timedatectl set-ntp true komutuyla senkronize edin. Ayrıca, güvenlik duvarınızın *.workers.dev adresine 443 portundan giden trafiğe izin verdiğinden emin olun.

sudo timedatectl set-ntp true
sudo timedatectl status
curl -I https://abs-license-activation.automatiaabs.workers.dev

Caddy TLS sertifikası alamıyor

Sitenize HTTPS ile erişemiyorsanız veya tarayıcınızda TLS/SSL hatası görüyorsanız, Caddy sertifika alamamış demektir. Bunun nedeni genellikle DNS kaydının henüz tam yayılmamış olması veya 80/443 portlarının kapalı olmasıdır. dig +short abs.sirketiniz.com komutunun sunucunuzun IP adresini döndürdüğünü doğrulayın. sudo ufw status ile 80 ve 443 portlarının açık olduğunu kontrol edin. Gerekirse sudo ufw allow 80,443 komutunu çalıştırın ve 5 dakika bekleyin.

dig +short your.hostname.com
sudo ufw status
docker compose logs caddy | tail -50

Backend bellek yetersizliği

backend servisi sürekli yeniden başlıyorsa veya loglarda OOMKilled (Out of Memory) hatası görüyorsanız, 4 GB RAM'lik taban yapılandırma iş yükünüz için yetersiz kalıyor demektir. En basit çözüm, sunucunuzu bir üst modele (örneğin Hetzner CX31 - 8 GB RAM, €5.83/ay) yükseltmektir. Alternatif olarak, .env dosyanıza bir LLM sağlayıcı anahtarı ekleyerek embedding işlemlerini sunucu dışına taşıyabilir ve bellek kullanımını azaltabilirsiniz.

docker stats --no-stream
docker compose logs backend | grep -i 'oom\|memory'
# free -h to check host memory

Admin paneline ulaşılamıyor

Sitenize eriştiğinizde 502 Bad Gateway hatası alıyorsanız ama docker ps komutunda caddy servisi çalışır görünüyorsa, muhtemelen landing servisi sağlık kontrolünü (healthcheck) geçemiyordur. docker compose logs landing komutuyla logları kontrol edin. Sık karşılaşılan bir neden, .env dosyasındaki ABS_PUBLIC_URL değişkeninin yanlış ayarlanmasıdır. Bu değişkenin https://abs.sirketiniz.com şeklinde tam URL içerdiğinden emin olun ve docker compose restart landing ile servisi yeniden başlatın.

docker compose logs landing | tail -50
# In .env, ensure:
# ABS_PUBLIC_URL=https://your.hostname.com
docker compose restart landing

Yardım ister misiniz?

Bu rehberdeki adımları izlemenize rağmen bir sorunla karşılaşırsanız, size yardımcı olmaktan memnuniyet duyarız. Lütfen size gönderdiğimiz hoş geldin e-postasını yanıtlayarak veya doğrudan founder@automatiabcn.com adresine yazarak bize ulaşın. Sorununuzu daha hızlı çözebilmemiz için e-postanıza docker compose logs komutunun çıktısını eklemeyi unutmayın. Genellikle tek bir e-posta ile sorunu çözebiliriz.

ABS