1. Ön Hazırlıklar ve Gerekli Araçlar

Günümüz yazılım geliştirme dünyasında hız ve güvenilirlik, rekabet avantajı sağlamanın anahtarlarıdır. Sürekli Entegrasyon (CI) ve Sürekli Dağıtım (CD) pratikleri, bu hedeflere ulaşmak için vazgeçilmez araçlar haline gelmiştir. Bu rehberde, GitLab CI/CD kullanarak kodunuzu bir Ubuntu sunucusuna otomatik olarak dağıtacak sağlam bir Sürekli Dağıtım (CD) hattını nasıl kuracağınızı adım adım öğreneceksiniz.

GitLab CI/CD, GitLab’ın kendisiyle entegre çalışan güçlü bir otomasyon aracıdır. Kod depolarınızla sorunsuz bir şekilde birleşerek, her kod değişikliğinde testleri çalıştırmanıza, derleme yapmanıza ve hatta uygulamanızı dağıtmanıza olanak tanır. Ubuntu ise, sunucu tarafında en popüler ve yaygın kullanılan işletim sistemlerinden biridir. Bu kombinasyon, geliştirme süreçlerinizi otomatikleştirmek ve manuel hataları en aza indirmek için ideal bir çözüm sunar.

Bu rehberin sonunda, bir Git push işlemiyle tetiklenen, testleri geçen ve uygulamanızı belirlediğiniz bir Ubuntu sunucusuna otomatik olarak dağıtan bir CI/CD hattına sahip olacaksınız. Bu, geliştiricilerin kodlarını daha hızlı ve güvenle canlıya almalarını sağlayarak, iş akışını önemli ölçüde hızlandıracaktır.

1. Ön Hazırlıklar ve Gerekli Araçlar

CD hattını kurmaya başlamadan önce bazı temel gereksinimleri ve araçları hazır etmemiz gerekiyor. Bu adımlar, sorunsuz bir kurulum süreci için kritik öneme sahiptir.

GitLab Projesi ve Kod Deposu

Öncelikle, dağıtımını yapacağınız uygulamanın kaynak kodunu içeren bir GitLab projeniz olmalı. Bu proje, CI/CD hattının tetikleneceği ana merkez olacaktır. Projenizin ana dalında (genellikle main veya master) dağıtıma hazır bir kod tabanınız olduğundan emin olun.

Hedef Ubuntu Sunucusu

Uygulamanızı dağıtacağımız bir Ubuntu sunucusuna ihtiyacımız var. Bu sunucuya SSH ile erişiminizin olması ve dağıtım işlemlerini gerçekleştirecek yetkilere sahip bir kullanıcı hesabınızın bulunması gerekmektedir. Sunucunuzun güncel olduğundan emin olmak için aşağıdaki komutu çalıştırabilirsiniz:

sudo apt update && sudo apt upgrade -y

Ayrıca, sunucunuzda uygulamanızın çalışması için gerekli olan tüm bağımlılıkların (Node.js, Python, Java Runtime vb.) kurulu olduğundan emin olun.

GitLab Runner

GitLab Runner, GitLab CI/CD işlerini çalıştıran bir aracıdır. Bu rehberde, Ubuntu sunucumuza bir GitLab Runner kurarak, CI/CD işlerinin doğrudan bu sunucu üzerinde çalışmasını sağlayacağız. Runner’lar, GitLab projenizdeki .gitlab-ci.yml dosyasında tanımlanan adımları yürütür.

SSH Anahtar Çifti

GitLab CI/CD hattımızın, Ubuntu sunucumuza güvenli bir şekilde bağlanıp komutları yürütebilmesi için SSH anahtar çifti kullanacağız. Bu, parola gerektirmeyen, otomatik ve güvenli bir bağlantı sağlar.

2. GitLab Runner Kurulumu ve Kaydı

CD hattımızın en kritik bileşenlerinden biri olan GitLab Runner’ı hedef Ubuntu sunucumuza kurup kaydedeceğiz. Bu sayede GitLab, dağıtım komutlarını bu Runner aracılığıyla sunucumuzda çalıştırabilecektir.

Runner Kurulumu

Ubuntu sunucunuzda aşağıdaki adımları izleyerek GitLab Runner’ı kurun:

1. Gerekli bağımlılıkları yükleyin:

   sudo apt update
   sudo apt install -y curl gnupg2
   

2. GitLab Runner deposunu ekleyin:

   curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" | sudo bash
   

3. GitLab Runner’ı yükleyin:

   sudo apt install gitlab-runner
   

Runner Kaydı

Runner’ı kurduktan sonra, onu GitLab projenize kaydetmeniz gerekir. Bu işlem, Runner’ın hangi GitLab projesiyle iletişim kuracağını belirler.

1. GitLab projenize gidin. Sol menüden Settings > CI/CD seçeneğine tıklayın.
2. Runners bölümünü genişletin. Burada, Runner’ınızı kaydetmek için gerekli olan GitLab URL’ini ve Kayıt Token’ını (Registration Token) bulacaksınız.
3. Ubuntu sunucunuzda aşağıdaki komutu çalıştırın:

   sudo gitlab-runner register
   

4. Komut sizden aşağıdaki bilgileri isteyecektir:
   • GitLab instance URL: GitLab projenizin URL’i (örn: https://gitlab.com veya kendi sunucunuzun URL’i).
   • Registration token: GitLab projenizin Runner ayarlarında bulduğunuz token.
   • Description for the runner: Runner için açıklayıcı bir isim (örn: ubuntu-deploy-runner).
   • Tags for the runner: Bu çok önemli bir adımdır. Runner’a etiketler atayın (örn: ubuntu, production, my-app-deploy). Bu etiketler, .gitlab-ci.yml dosyanızda belirli işleri bu Runner’a atamak için kullanılacaktır.
   • Executor: shell seçeneğini girin. Bu, işlerin doğrudan sunucunun kabuk ortamında çalıştırılmasını sağlar. (Daha karmaşık senaryolar için Docker veya Kubernetes de seçilebilir).

Başarılı bir kaydın ardından, GitLab projenizin Runner’lar sayfasında yeni Runner’ınızı “Online” olarak görmelisiniz.

3. Dağıtım İçin SSH Erişimi Ayarları

GitLab CI/CD hattının Ubuntu sunucumuza güvenli ve otomatik olarak bağlanabilmesi için SSH anahtar çifti kullanacağız. Bu anahtar çiftini oluşturacak ve GitLab CI/CD değişkeni olarak güvenli bir şekilde saklayacağız.

SSH Anahtar Çifti Oluşturma

Yerel makinenizde (veya GitLab Runner’ın çalıştığı sunucuda geçici olarak) yeni bir SSH anahtar çifti oluşturun. Bu anahtarı kimseyle paylaşmayın ve güvenli bir yerde saklayın:

ssh-keygen -t rsa -b 4096 -C "gitlab-deploy-key" -f ~/.ssh/gitlab-deploy-key

Bu komut, ~/.ssh/gitlab-deploy-key (private key) ve ~/.ssh/gitlab-deploy-key.pub (public key) adında iki dosya oluşturacaktır. Parola sormazsa, boş bırakmak için Enter tuşuna basın.

Public Key’i Ubuntu Sunucusuna Ekleme

Oluşturduğumuz public key’i (~/.ssh/gitlab-deploy-key.pub) Ubuntu sunucunuzdaki dağıtım kullanıcısının ~/.ssh/authorized_keys dosyasına eklemeniz gerekiyor. Bu sayede, private key’e sahip olan herhangi bir sistem, bu kullanıcı olarak sunucuya parola girmeden bağlanabilecektir.

Public key’in içeriğini kopyalayın:

cat ~/.ssh/gitlab-deploy-key.pub

Kopyaladığınız içeriği Ubuntu sunucunuzdaki dağıtım kullanıcısının (örn: deployuser) ~/.ssh/authorized_keys dosyasına ekleyin. Eğer dosya veya dizin yoksa oluşturun ve doğru izinleri verin:

# Ubuntu sunucusunda
mkdir -p ~/.ssh
chmod 700 ~/.ssh
nano ~/.ssh/authorized_keys # veya tercih ettiğiniz editör
Kopyaladığınız public key'i bu dosyaya yapıştırın ve kaydedin
chmod 600 ~/.ssh/authorized_keys

Bu adımdan sonra, private key’i kullanarak Ubuntu sunucunuza parola sormadan SSH bağlantısı kurabilmeniz gerekir. Test etmek için yerel makinenizden deneyebilirsiniz:

ssh -i ~/.ssh/gitlab-deploy-key deployuser@your_ubuntu_server_ip

GitLab CI/CD Değişkeni Olarak Private Key Ekleme

Şimdi, oluşturduğumuz private key’i GitLab projemizin CI/CD değişkenlerine ekleyeceğiz. Bu, private key’in .gitlab-ci.yml dosyasında doğrudan görünmeden güvenli bir şekilde kullanılmasına olanak tanır.

1. GitLab projenize gidin. Sol menüden Settings > CI/CD seçeneğine tıklayın.
2. Variables bölümünü genişletin ve Add Variable düğmesine tıklayın.
3. Key alanına SSH_PRIVATE_KEY yazın.
4. Value alanına, ~/.ssh/gitlab-deploy-key dosyasının tüm içeriğini (-----BEGIN RSA PRIVATE KEY----- ile başlayıp -----END RSA PRIVATE KEY----- ile biten tüm bloğu) yapıştırın.
5. Type olarak File seçeneğini seçin. (Bu, içeriği bir dosya olarak CI/CD ortamına sunar, bu da SSH agent için daha kullanışlıdır.)
6. Protect variable kutucuğunu işaretleyin. Bu, değişkenin sadece korumalı dallarda veya etiketlerde çalışmasını sağlar.
7. Mask variable kutucuğunu işaretleyin. Bu, değişkenin pipeline loglarında görünmesini engeller ve güvenlik açısından önemlidir.
8. Add variable düğmesine tıklayarak kaydedin.

4. .gitlab-ci.yml Dosyasını Yapılandırma

GitLab CI/CD hattının kalbi, projenizin kök dizininde bulunan .gitlab-ci.yml dosyasıdır. Bu dosya, CI/CD işlerinin hangi aşamalardan oluşacağını, hangi komutları çalıştıracağını ve hangi koşullar altında tetikleneceğini tanımlar.

Temel Yapı ve Aşamalar

Tipik bir .gitlab-ci.yml dosyası, stages (aşamalar) ve her aşamaya ait işleri (jobs) tanımlar. Örneğin, bir web uygulaması için genellikle build (derleme), test (test etme) ve deploy (dağıtım) aşamaları bulunur.

stages:
  - build
  - test
  - deploy

image: node:18-alpine # Uygulamanızın türüne göre (node, python, ruby vb.) değiştirin

cache:
  paths:
    - node_modules/ # Bağımlılıkları önbelleğe alarak build sürelerini kısaltın

variables:
  APP_DIR: /var/www/my-awesome-app # Ubuntu sunucusundaki uygulama dizini
  SSH_USER: deployuser # Ubuntu sunucusundaki SSH kullanıcısı
  SSH_HOST: your_ubuntu_server_ip # Ubuntu sunucunuzun IP adresi veya hostname

build_job:
  stage: build
  script:
    - echo "Uygulama derleniyor..."
    - npm install
    - npm run build
  artifacts:
    paths:
      - build/ # Derlenen dosyaları sonraki aşamalar için sakla
    expire_in: 1 day

test_job:
  stage: test
  script:
    - echo "Uygulama testleri çalıştırılıyor..."
    - npm test
  # Sadece main branch'inde çalıştır
  only:
    - main

deploy_production:
  stage: deploy
  environment:
    name: production
    url: http://your_ubuntu_server_ip # Canlı uygulamanızın URL'i
  before_script:
    - chmod 400 $SSH_PRIVATE_KEY # Private key'e doğru izinleri ver
    - eval "$(ssh-agent -s)" # SSH agent'ı başlat
    - ssh-add $SSH_PRIVATE_KEY # Private key'i agent'a ekle
    - mkdir -p ~/.ssh
    - echo -e "Host *\n\tStrictHostKeyChecking no\n\tUserKnownHostsFile /dev/null" > ~/.ssh/config # Host anahtar kontrolünü devre dışı bırak (güvenlik uyarısı aşağıda)
  script:
    - echo "Dağıtım başlatılıyor..."
    - ssh ${SSH_USER}@${SSH_HOST} "mkdir -p ${APP_DIR} && cd ${APP_DIR} && git pull origin main" # Sunucuda dizini oluştur ve kodu çek
    - ssh ${SSH_USER}@${SSH_HOST} "cd ${APP_DIR} && npm install --production && npm run build" # Bağımlılıkları yükle ve yeniden derle
    - ssh ${SSH_USER}@${SSH_HOST} "sudo systemctl restart my-app-service" # Uygulama servisini yeniden başlat (servis adını değiştirin)
    - echo "Dağıtım tamamlandı!"
  only:
    - main # Sadece main branch'ine yapılan push'larda dağıtım yap
  tags:
    - ubuntu-deploy-runner # Runner kaydı sırasında belirlediğiniz etiket

Kod Örneği Açıklaması

• stages: Pipeline’ın aşamalarını tanımlar.
• image: İşlerin çalışacağı Docker imajını belirtir. Uygulamanızın teknolojisine göre (Node.js, Python, PHP vb.) uygun bir imaj seçmelisiniz.
• cache: Bağımlılıkları (örn: node_modules) önbelleğe alarak sonraki CI/CD çalıştırmalarını hızlandırır.
• variables: Pipeline genelinde kullanılabilecek değişkenleri tanımlar. Burada Ubuntu sunucusunun dizin, kullanıcı ve IP bilgilerini saklıyoruz.
• build_job: Uygulamanın bağımlılıklarını kurup derlendiği aşama. artifacts ile derlenen dosyaları sonraki aşamalara aktarırız.
• test_job: Uygulamanın testlerinin koşulduğu aşama. only: - main ile sadece main branch’inde çalışmasını sağlarız.
• deploy_production:
  • stage: deploy: Bu işin dağıtım aşamasında olduğunu belirtir.
  • environment: GitLab’ın ortam özelliklerini kullanır.
  • before_script: Her işin script bölümü çalışmadan önce yürütülen komutlardır.
    • chmod 400 $SSH_PRIVATE_KEY: GitLab değişkeni olarak eklediğimiz private key dosyasının (Type: File olduğu için bir dosya olarak erişilebilir) izinlerini ayarlar.
    • eval "$(ssh-agent -s)" ve ssh-add $SSH_PRIVATE_KEY: SSH agent’ı başlatır ve private key’i agent’a ekler. Bu sayede sonraki ssh komutları otomatik olarak bu anahtarı kullanır.
    • echo -e "Host ... StrictHostKeyChecking no": Bu satır, ilk SSH bağlantısında sunucu anahtar parmak izini sormayı devre dışı bırakır. Güvenlik Notu: Üretim ortamlarında bu ayarı kullanırken dikkatli olun. Daha güvenli bir yaklaşım, bilinen anahtarları (known_hosts) GitLab değişkeni olarak eklemek veya SSH tarayıcı parmak izini önceden eklemektir. Ancak basit CD kurulumları için bu pratik bir yaklaşımdır.
  • script: Dağıtımın asıl adımları burada yer alır.
    • ssh ${SSH_USER}@${SSH_HOST} "...": Uzak Ubuntu sunucusunda komutları yürütür.
      • mkdir -p ${APP_DIR} && cd ${APP_DIR} && git pull origin main: Uygulama dizinini oluşturur, oraya gider ve kod deposunu çeker.
      • npm install --production && npm run build: Uygulamanın bağımlılıklarını kurar ve yeniden derler. Uygulamanızın gereksinimlerine göre bu komutlar değişebilir (örn: pip install -r requirements.txt, composer install).
      • sudo systemctl restart my-app-service: Uygulamanızın sistem servisini yeniden başlatır. Uygulamanızın nasıl çalıştığına bağlı olarak bu komutu ayarlamanız gerekir (örn: pm2 restart my-app, gunicorn restart).
  • only: - main: Bu işin sadece main branch’ine yapılan push’larda tetiklenmesini sağlar.
  • tags: - ubuntu-deploy-runner: Bu işi, daha önce kaydettiğimiz ve bu etikete sahip olan Runner’ın çalıştırmasını sağlar. Bu, birden fazla Runner’ınız olduğunda belirli işleri belirli sunuculara atamak için kullanılır.

5. Dağıtım Sonrası Kontroller ve İyileştirmeler

CD hattını kurduktan sonra, her şeyin beklendiği gibi çalıştığından emin olmak ve gelecekteki iyileştirmeler için bazı noktaları göz önünde bulundurmak önemlidir.

Hata Ayıklama (Troubleshooting)

Pipeline’ınız başarısız olursa endişelenmeyin. GitLab CI/CD, her iş için detaylı loglar sunar. Pipeline’ınızın çıktısını dikkatlice inceleyerek hatanın nerede olduğunu belirleyebilirsiniz:

• SSH Bağlantı Sorunları: Loglarda “Permission denied (publickey)” veya “Host key verification failed” gibi hatalar görüyorsanız, SSH anahtar çiftinizin doğru ayarlandığından, public key’in Ubuntu sunucusundaki authorized_keys dosyasına doğru eklendiğinden ve SSH_PRIVATE_KEY değişkeninin GitLab’da doğru değerle ve izinlerle tanımlandığından emin olun.
• Komut Hataları: Uzak sunucuda çalıştırılan komutlarda (git pull, npm install, systemctl restart vb.) hatalar alıyorsanız, komutların Ubuntu sunucusunda manuel olarak çalıştırıldığında da aynı hatayı verip vermediğini kontrol edin. İzin sorunları, bağımlılık eksiklikleri veya yanlış dizinler yaygın nedenlerdir.
• Runner Etiketi: İşinizin çalışmadığını görüyorsanız, .gitlab-ci.yml dosyasındaki tags bölümünün, Runner kaydı sırasında verdiğiniz etiketle tam olarak eşleştiğinden emin olun.

İyileştirme Önerileri

Bu temel CD hattını kurduktan sonra, projenizin ihtiyaçlarına göre daha da geliştirebilirsiniz:

• Ortam Değişkenleri: Geliştirme, hazırlık (staging) ve üretim (production) gibi farklı ortamlar için ayrı dağıtım işleri oluşturabilir ve her ortam için farklı değişkenler (veritabanı bağlantı bilgileri, API anahtarları vb.) kullanabilirsiniz.
• Rollback Stratejileri: Dağıtım sonrası kritik bir hata oluşursa, hızlı bir şekilde önceki sürüme dönmenizi sağlayacak bir geri alma (rollback) stratejisi ekleyin. Bu, genellikle önceki bir Git commit’ine dönmek veya uygulamanın önceki bir derlemesini yeniden dağıtmak şeklinde olabilir.
• Docker Compose Kullanımı: Uygulamanız birden fazla servisten (veritabanı, ön uç, arka uç vb.) oluşuyorsa, Docker Compose kullanarak dağıtım sürecini daha da basitleştirebilirsiniz. Runner’ınızda Docker executor kullanmak bu senaryoda daha uygun olabilir.
• Bildirimler: Dağıtımın başarılı veya başarısız olduğu durumlarda Slack, E-posta veya diğer araçlar aracılığıyla bildirimler göndererek ekip üyelerini bilgilendirebilirsiniz.
• Güvenlik İyileştirmeleri: StrictHostKeyChecking no yerine, ilk bağlantıda host key’i manuel olarak ekleyerek veya bir GitLab değişkeni aracılığıyla known_hosts dosyasını oluşturarak daha güvenli bir SSH bağlantısı sağlayabilirsiniz.
• Veritabanı Migrasyonları: Uygulamanız veritabanı kullanıyorsa, dağıtım sonrası veritabanı migrasyonlarını otomatik olarak çalıştıracak adımlar eklemeyi unutmayın.

Sonuç ve Sıkça Sorulan Sorular

Bu rehberde, GitLab CI/CD kullanarak bir Ubuntu sunucusuna otomatik dağıtım yapan bir Sürekli Dağıtım hattını nasıl kuracağınızı öğrendiniz. GitLab Runner’ın kurulumundan, SSH anahtar çifti yönetimine ve .gitlab-ci.yml dosyasının yapılandırmasına kadar tüm önemli adımları ele aldık. Artık kod değişikliklerinizi daha hızlı, güvenli ve otomatik bir şekilde canlıya alabilirsiniz. Bu, geliştirme süreçlerinizi optimize etmenize ve pazarınıza daha hızlı değer sunmanıza yardımcı olacaktır.

Sıkça Sorulan Sorular (SSS)

S: Neden StrictHostKeyChecking=no kullanıldı ve bu güvenli mi?
C: StrictHostKeyChecking=no, SSH bağlantısı sırasında sunucunun anahtar parmak izini ilk kez doğrulamayı atlar. CI/CD ortamında, manuel etkileşimi ortadan kaldırmak için bazen kullanılır. Ancak, bu, potansiyel bir “man-in-the-middle” saldırısına karşı daha savunmasız hale getirir. Üretim ortamlarında, daha güvenli bir yaklaşım, sunucunun anahtar parmak izini (public key’ini) önceden known_hosts dosyasına eklemek veya GitLab CI/CD değişkeni olarak güvenli bir şekilde saklamaktır.

S: Birden fazla sunucuya nasıl dağıtım yapılır?
C: Birden fazla sunucuya dağıtım yapmak için .gitlab-ci.yml dosyanızda her sunucu için ayrı bir dağıtım işi tanımlayabilir veya bir döngü içinde tüm sunuculara dağıtım yapacak bir script yazabilirsiniz. Her sunucu için farklı SSH_HOST değişkenleri veya etiketlenmiş farklı Runner’lar kullanabilirsiniz.

S: Runner’ı Docker executor olarak kullanmanın avantajları nelerdir?
C: Docker executor kullanmak, her CI/CD işinin izole bir Docker konteyneri içinde çalışmasını sağlar. Bu, bağımlılık çakışmalarını önler, ortamın tutarlılığını garanti eder ve işlerin yerel makinenizdeki ortamdan tamamen bağımsız olmasını sağlar. Özellikle farklı projeler veya farklı bağımlılıklara sahip aşamalar için çok kullanışlıdır.

S: Dağıtım sonrası veritabanı migrasyonları nasıl yönetilir?
C: Veritabanı migrasyonları, .gitlab-ci.yml dosyasındaki dağıtım aşamasının bir parçası olarak çalıştırılabilir. Örneğin, uygulamanız bir ORM (Object-Relational Mapper) kullanıyorsa, dağıtım script’inize ssh ${SSH_USER}@${SSH_HOST} "cd ${APP_DIR} && python manage.py migrate" (Django için) veya ssh ${SSH_USER}@${SSH_HOST} "cd ${APP_DIR} && npx prisma migrate deploy" (Prisma için) gibi bir komut ekleyebilirsiniz. Bu komutların, uygulamanızın kod tabanını güncelledikten hemen sonra çalıştırılması önemlidir.