balikci/DOCKER.md

🐳 Docker Deployment Guide

Oltalama Test Yönetim Paneli - Docker ile Kurulum

Bu dokümantasyon, projeyi Docker ve Docker Compose kullanarak nasıl çalıştıracağınızı açıklar.

---

📋 İçindekiler

• Gereksinimler
• Hızlı Başlangıç
• Development Modu
• Production Modu
• Ortam Değişkenleri
• Veri Yedekleme
• İleri Seviye Kullanım

---

🔧 Gereksinimler

• Docker: 20.10 veya üzeri
• Docker Compose: 2.0 veya üzeri
• Git: (projeyi klonlamak için)

Docker Kurulumu

Ubuntu/Debian:

# Docker kurulumu
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Docker Compose kurulumu (eğer yoksa)
sudo apt-get install docker-compose-plugin

# Kullanıcıyı docker grubuna ekle
sudo usermod -aG docker $USER
newgrp docker

RedHat/Oracle/CentOS:

# Docker kurulumu
sudo dnf install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# Docker'ı başlat ve aktifleştir
sudo systemctl start docker
sudo systemctl enable docker

# Kullanıcıyı docker grubuna ekle
sudo usermod -aG docker $USER
newgrp docker

---

🚀 Hızlı Başlangıç

1. Projeyi Klonlayın

git clone <repository-url> oltalama
cd oltalama

2. Environment Dosyasını Hazırlayın

# Örnek dosyadan kopyalayın
cat > .env << 'EOF'
SESSION_SECRET=your-strong-random-secret-here
GMAIL_USER=your-email@gmail.com
GMAIL_APP_PASSWORD=your-gmail-app-password
TELEGRAM_BOT_TOKEN=your-bot-token
TELEGRAM_CHAT_ID=your-chat-id
OLLAMA_SERVER_URL=http://host.docker.internal:11434
OLLAMA_MODEL=llama3.2:latest
VITE_API_URL=http://localhost:3000
EOF

# Editör ile açın ve konfigüre edin
nano .env

Minimum gerekli ayarlar:

SESSION_SECRET=very-strong-random-secret-here
GMAIL_USER=your-email@gmail.com
GMAIL_APP_PASSWORD=your-gmail-app-password
TELEGRAM_BOT_TOKEN=your-bot-token
TELEGRAM_CHAT_ID=your-chat-id

3. Production Modunda Başlatın

# Container'ları build edin ve başlatın
docker compose up -d

# Logları görüntüleyin
docker compose logs -f

4. Admin Kullanıcısı Oluşturun

İlk çalıştırmada admin kullanıcısı oluşturmanız gerekir:

# Backend container'a bağlanın
docker compose exec backend sh

# Admin kullanıcı scripti çalıştırın
node scripts/create-admin.js

# Container'dan çıkın
exit

5. Uygulamaya Erişin

• Frontend: http://localhost:4173
• Backend API: http://localhost:3000
• Health Check: http://localhost:3000/health

---

💻 Development Modu

Development modunda hot-reload aktif olur ve kod değişiklikleri anında yansır.

Başlatma

# Development compose ile başlat
docker compose -f docker-compose.dev.yml up

# Veya arka planda çalıştır
docker compose -f docker-compose.dev.yml up -d

Özellikler

• ✅ Hot Reload: Kod değişiklikleri anında yansır
• ✅ Volume Mount: Local klasörler container'a mount edilir
• ✅ Debug Modu: Detaylı log çıktıları
• ✅ Nodemon: Backend için otomatik restart

Development Portları

• Frontend (Vite Dev Server): http://localhost:5173
• Backend: http://localhost:3000

---

🏭 Production Modu

Production modu için optimize edilmiş, multi-stage build ile küçük image boyutu.

Başlatma

# Production compose ile başlat
docker compose up -d

# Durum kontrolü
docker compose ps

# Logları görüntüle
docker compose logs -f backend
docker compose logs -f frontend

Container Yönetimi

# Tüm servisleri durdur
docker compose stop

# Tüm servisleri başlat
docker compose start

# Tüm servisleri yeniden başlat
docker compose restart

# Servisleri kaldır (veri korunur)
docker compose down

# Servisleri ve volume'leri kaldır (VERİ SİLİNİR!)
docker compose down -v

Build İşlemleri

# Image'ları yeniden build et
docker compose build

# Cache kullanmadan build et
docker compose build --no-cache

# Belirli bir servisi build et
docker compose build backend

---

🔐 Ortam Değişkenleri

Backend Değişkenleri

Değişken	Açıklama	Varsayılan	Zorunlu
NODE_ENV	Çalışma ortamı	production	❌
PORT	Backend portu	3000	❌
SESSION_SECRET	Session şifreleme anahtarı	-	✅
GMAIL_USER	Gmail hesabı	-	✅
GMAIL_APP_PASSWORD	Gmail uygulama şifresi	-	✅
TELEGRAM_BOT_TOKEN	Telegram bot token	-	✅
TELEGRAM_CHAT_ID	Telegram chat ID	-	✅
DOMAIN_URL	Backend domain	http://localhost:3000	❌
FRONTEND_URL	Frontend domain	http://localhost:4173	❌
OLLAMA_SERVER_URL	Ollama AI server URL	http://host.docker.internal:11434	❌
OLLAMA_MODEL	Ollama model adı	llama3.2:latest	❌

Frontend Değişkenleri

Değişken	Açıklama	Varsayılan	Zorunlu
VITE_API_URL	Backend API URL	http://localhost:3000	✅

---

💾 Veri Yedekleme

Manuel Yedekleme

# Database yedekle
docker compose exec backend sh -c "cd database && tar czf /tmp/backup.tar.gz *.db"
docker compose cp backend:/tmp/backup.tar.gz ./backup-$(date +%Y%m%d).tar.gz

# Logs yedekle
docker compose exec backend sh -c "cd logs && tar czf /tmp/logs-backup.tar.gz *.log"
docker compose cp backend:/tmp/logs-backup.tar.gz ./logs-backup-$(date +%Y%m%d).tar.gz

Otomatik Yedekleme (Cron)

# Yedekleme scripti oluştur
cat > backup.sh << 'EOF'
#!/bin/bash
BACKUP_DIR="/backup/oltalama"
DATE=$(date +%Y%m%d_%H%M%S)

mkdir -p $BACKUP_DIR

# Database backup
docker compose exec -T backend sh -c "cd database && tar czf - *.db" > "$BACKUP_DIR/db-$DATE.tar.gz"

# Eski yedekleri sil (30 günden eski)
find $BACKUP_DIR -name "db-*.tar.gz" -mtime +30 -delete

echo "Backup completed: $DATE"
EOF

chmod +x backup.sh

# Crontab'a ekle (her gün 02:00'de)
(crontab -l 2>/dev/null; echo "0 2 * * * /path/to/backup.sh >> /var/log/oltalama-backup.log 2>&1") | crontab -

Geri Yükleme

# Database geri yükle
docker compose cp ./backup-20250101.tar.gz backend:/tmp/
docker compose exec backend sh -c "cd database && tar xzf /tmp/backup-20250101.tar.gz"
docker compose restart backend

---

🔧 İleri Seviye Kullanım

Nginx ile Reverse Proxy

Nginx reverse proxy eklemek için:

# Nginx profili ile başlat
docker compose --profile with-nginx up -d

nginx.conf dosyasını düzenleyin:

# nginx/nginx.conf
server {
    listen 80;
    server_name yourdomain.com;

    location / {
        proxy_pass http://frontend:4173;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }

    location /api/ {
        proxy_pass http://backend:3000/api/;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

Resource Limits

Production ortamında resource limitleri ekleyin:

# docker-compose.yml içine ekle
services:
  backend:
    # ... diğer ayarlar
    deploy:
      resources:
        limits:
          cpus: '1'
          memory: 512M
        reservations:
          cpus: '0.5'
          memory: 256M

Health Check Monitoring

Container'ların sağlık durumunu izleyin:

# Health status kontrolü
docker compose ps

# Detaylı health check logları
docker inspect --format='{{json .State.Health}}' oltalama-backend | jq

Ollama ile Kullanım

Eğer Ollama host makinede çalışıyorsa:

# Host'tan Ollama'ya erişim için
# .env dosyasında:
OLLAMA_SERVER_URL=http://host.docker.internal:11434
OLLAMA_MODEL=llama3.2:latest

Ollama'yı da Docker'da çalıştırmak için:

# docker-compose.yml'e ekle
services:
  ollama:
    image: ollama/ollama:latest
    container_name: oltalama-ollama
    restart: unless-stopped
    ports:
      - "11434:11434"
    volumes:
      - ollama-data:/root/.ollama
    networks:
      - oltalama-network

volumes:
  ollama-data:
    driver: local

Sonra .env dosyasında:

OLLAMA_SERVER_URL=http://ollama:11434

---

🐛 Troubleshooting

Problem: Container başlamıyor

# Logları kontrol et
docker compose logs backend
docker compose logs frontend

# Container'ı interaktif başlat
docker compose run --rm backend sh

Problem: Database erişim hatası

# Volume'leri kontrol et
docker volume ls
docker volume inspect oltalama_backend-data

# İzinleri düzelt
docker compose exec backend chown -R oltalama:oltalama /app/database

Problem: Port conflict

# Kullanılan portları kontrol et
sudo lsof -i :3000
sudo lsof -i :4173

# Farklı port kullan
docker compose up -d --force-recreate

Problem: Image boyutu çok büyük

# Kullanılmayan image'ları temizle
docker system prune -a

# Build cache'i temizle
docker builder prune

---

📊 Monitoring

Container İstatistikleri

# Gerçek zamanlı resource kullanımı
docker stats

# Belirli container'lar için
docker stats oltalama-backend oltalama-frontend

Log Yönetimi

# Son 100 satır
docker compose logs --tail=100 backend

# Gerçek zamanlı takip
docker compose logs -f

# Belirli bir zaman aralığı
docker compose logs --since="2025-01-01T00:00:00"

# Belirli bir service
docker compose logs backend

---

🚀 Production Deployment Checklist

• .env dosyasını production değerleri ile doldur
• SESSION_SECRET için güçlü random string oluştur
• Gmail App Password oluştur ve ayarla
• Telegram bot token ve chat ID ayarla
• Domain URL'lerini güncelle
• Nginx reverse proxy yapılandır (opsiyonel)
• SSL/TLS sertifikası ekle
• Firewall kurallarını ayarla
• Admin kullanıcı oluştur
• Otomatik yedekleme sistemi kur
• Health check monitoring kur
• Log rotation yapılandır

---

📚 Ek Kaynaklar

• Docker Documentation
• Docker Compose Documentation
• Best Practices for Node.js in Docker

---

🆘 Destek

Sorun yaşıyorsanız:

1. Logları kontrol edin: docker compose logs
2. Container durumunu kontrol edin: docker compose ps
3. Health check durumunu kontrol edin
4. Issue açın veya dokümantasyonu inceleyin

---

🎉 Artık Docker ile hazırsınız!