629 lines
14 KiB
Markdown
629 lines
14 KiB
Markdown
# 🐳 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](#gereksinimler)
|
||
- [Hızlı Başlangıç](#hızlı-başlangıç)
|
||
- [Development Modu](#development-modu)
|
||
- [Production Modu](#production-modu)
|
||
- [Ortam Değişkenleri](#ortam-değişkenleri)
|
||
- [Veri Yedekleme](#veri-yedekleme)
|
||
- [İleri Seviye Kullanım](#ileri-seviye-kullanım)
|
||
|
||
---
|
||
|
||
## 🔧 Gereksinimler
|
||
|
||
- **Docker**: 20.10 veya üzeri
|
||
- **Docker Compose**: 2.0 veya üzeri
|
||
- **Git**: (projeyi klonlamak için)
|
||
|
||
### Docker Kurulumu
|
||
|
||
#### Ubuntu/Debian:
|
||
```bash
|
||
# 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:
|
||
```bash
|
||
# 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
|
||
|
||
```bash
|
||
git clone <repository-url> oltalama
|
||
cd oltalama
|
||
```
|
||
|
||
### 2. Environment Dosyasını Hazırlayın
|
||
|
||
**🎉 Yeni: SESSION_SECRET Artık Otomatik Oluşuyor!**
|
||
|
||
Docker entrypoint scripti sayesinde SESSION_SECRET'ı belirtmeseniz bile **otomatik oluşturulur** ve kaydedilir.
|
||
|
||
#### Seçenek 1: Minimal (Otomatik SESSION_SECRET)
|
||
|
||
```bash
|
||
# Sadece zorunlu ayarları girin, SESSION_SECRET otomatik!
|
||
cat > .env << 'EOF'
|
||
# SESSION_SECRET boş bırakılırsa otomatik oluşturulur!
|
||
c
|
||
EOF
|
||
```
|
||
|
||
#### Seçenek 2: Manuel SESSION_SECRET (Daha Güvenli)
|
||
|
||
🔐 **Kendi SESSION_SECRET'ınızı Oluşturun:**
|
||
```bash
|
||
# Terminal'de çalıştır
|
||
node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"
|
||
# VEYA
|
||
openssl rand -hex 64
|
||
```
|
||
|
||
```bash
|
||
cat > .env << 'EOF'
|
||
# SESSION_SECRET: Oturumları şifreler (manuel oluşturduysanız buraya yapıştırın)
|
||
SESSION_SECRET=a3f8d92c7e1b4f5a9d8c7e2b1a4f5c8d9e2f1a3b4c5d6e7f8a9b0c1d2e3f4a5b
|
||
|
||
# Gmail ayarları
|
||
GMAIL_USER=your-email@gmail.com
|
||
GMAIL_APP_PASSWORD=your-gmail-app-password
|
||
|
||
# Telegram ayarları
|
||
TELEGRAM_BOT_TOKEN=your-bot-token
|
||
TELEGRAM_CHAT_ID=your-chat-id
|
||
|
||
# Opsiyonel: Otomatik seed data (ilk kurulumda örnek veri)
|
||
AUTO_SEED=false
|
||
|
||
# Ollama AI (opsiyonel)
|
||
OLLAMA_SERVER_URL=http://host.docker.internal:11434
|
||
OLLAMA_MODEL=llama3.2:latest
|
||
|
||
# Frontend
|
||
VITE_API_URL=http://localhost:3000
|
||
EOF
|
||
```
|
||
|
||
**Editörle düzenleyin:**
|
||
```bash
|
||
nano .env
|
||
```
|
||
|
||
### 3. Production Modunda Başlatın
|
||
|
||
```bash
|
||
# Container'ları build edin ve başlatın
|
||
docker compose up -d
|
||
|
||
# Logları görüntüleyin (SESSION_SECRET otomatik oluşturuldu mu kontrol edin)
|
||
docker compose logs backend
|
||
|
||
# Örnek çıktı:
|
||
# 🚀 Oltalama Backend başlatılıyor...
|
||
# 🔑 Yeni SESSION_SECRET otomatik oluşturuluyor...
|
||
# ✅ Yeni SESSION_SECRET oluşturuldu ve .env dosyasına kaydedildi
|
||
# 📝 SESSION_SECRET: a3f8d92c7e1b4f5a9d... (ilk 20 karakter)
|
||
# ✅ Backend hazır, uygulama başlatılıyor...
|
||
```
|
||
|
||
**🎉 SESSION_SECRET Otomatik Yönetimi:**
|
||
- ✅ İlk çalıştırmada otomatik oluşturulur
|
||
- ✅ Backend volume'üne kaydedilir
|
||
- ✅ Sonraki restart'larda aynı secret kullanılır
|
||
- ✅ Session'lar korunur
|
||
|
||
### 4. Admin Kullanıcısı Oluşturun
|
||
|
||
İlk çalıştırmada admin kullanıcısı oluşturmanız gerekir:
|
||
|
||
```bash
|
||
# 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
|
||
|
||
#### Single Container (Önerilen):
|
||
- **Frontend + API**: http://localhost:3000
|
||
- **Health Check**: http://localhost:3000/health
|
||
|
||
#### Multi-Container:
|
||
- **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
|
||
|
||
```bash
|
||
# 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
|
||
|
||
### 🎯 Single Container Setup (Önerilen)
|
||
|
||
**Tek container, tek port (3000)** - En basit ve önerilen yöntem!
|
||
|
||
Single container setup'ta:
|
||
- ✅ **Tek Port**: Sadece 3000 portu kullanılır
|
||
- ✅ **Backend + Frontend**: Backend hem API'yi hem frontend'i serve eder
|
||
- ✅ **CORS Yok**: Aynı origin'den geldiği için CORS sorunu yok
|
||
- ✅ **Daha Az Kaynak**: Tek container, daha az memory/CPU
|
||
- ✅ **Basit Yönetim**: Tek container yönetimi
|
||
|
||
#### Başlatma
|
||
|
||
```bash
|
||
# Single container ile başlat
|
||
docker compose -f docker-compose.single.yml up -d --build
|
||
|
||
# Durum kontrolü
|
||
docker compose -f docker-compose.single.yml ps
|
||
|
||
# Logları görüntüle
|
||
docker compose -f docker-compose.single.yml logs -f oltalama
|
||
```
|
||
|
||
#### Port Yapısı
|
||
|
||
```
|
||
Tek Port: 3000
|
||
├── /api/* → Backend API
|
||
├── /t/* → Tracking routes
|
||
├── /health → Health check
|
||
└── /* → Frontend SPA (React Router)
|
||
```
|
||
|
||
#### Nginx Proxy Manager Konfigürasyonu
|
||
|
||
Single container için:
|
||
- **Forward Hostname/IP**: `localhost`
|
||
- **Forward Port**: `3000`
|
||
- **SSL**: ✓ (Let's Encrypt)
|
||
- **Websockets**: ✓ (opsiyonel)
|
||
|
||
Tüm trafik (API + Frontend) → `localhost:3000`
|
||
|
||
#### Erişim
|
||
|
||
- **Frontend + API**: http://localhost:3000
|
||
- **Health Check**: http://localhost:3000/health
|
||
- **API Endpoint**: http://localhost:3000/api
|
||
|
||
---
|
||
|
||
### 🔄 Multi-Container Setup (Alternatif)
|
||
|
||
İki ayrı container (backend + frontend) - Daha esnek ama daha karmaşık.
|
||
|
||
#### Başlatma
|
||
|
||
```bash
|
||
# 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
|
||
```
|
||
|
||
#### Port Yapısı
|
||
|
||
- **Backend**: 3000 portu
|
||
- **Frontend**: 4173 portu (ayrı container)
|
||
|
||
### Container Yönetimi
|
||
|
||
```bash
|
||
# 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
|
||
|
||
```bash
|
||
# 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
|
||
|
||
```bash
|
||
# 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)
|
||
|
||
```bash
|
||
# 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
|
||
|
||
```bash
|
||
# 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:
|
||
|
||
```bash
|
||
# Nginx profili ile başlat
|
||
docker compose --profile with-nginx up -d
|
||
```
|
||
|
||
`nginx.conf` dosyasını düzenleyin:
|
||
|
||
```nginx
|
||
# nginx/nginx.conf
|
||
server {
|
||
listen 80;
|
||
server_name yourdomain.com;
|
||
|
||
# Single Container Setup için (Önerilen)
|
||
location / {
|
||
proxy_pass http://localhost:3000;
|
||
proxy_http_version 1.1;
|
||
proxy_set_header Upgrade $http_upgrade;
|
||
proxy_set_header Connection 'upgrade';
|
||
proxy_set_header Host $host;
|
||
proxy_set_header X-Real-IP $remote_addr;
|
||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||
proxy_set_header X-Forwarded-Proto $scheme;
|
||
proxy_cache_bypass $http_upgrade;
|
||
}
|
||
|
||
# Multi-Container Setup için (Alternatif)
|
||
# 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:
|
||
|
||
```yaml
|
||
# 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:
|
||
|
||
```bash
|
||
# 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:
|
||
|
||
```bash
|
||
# 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:
|
||
|
||
```yaml
|
||
# 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:
|
||
```env
|
||
OLLAMA_SERVER_URL=http://ollama:11434
|
||
```
|
||
|
||
---
|
||
|
||
## 🐛 Troubleshooting
|
||
|
||
### Problem: Container başlamıyor
|
||
|
||
```bash
|
||
# 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ı
|
||
|
||
```bash
|
||
# 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
|
||
|
||
```bash
|
||
# 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
|
||
|
||
```bash
|
||
# Kullanılmayan image'ları temizle
|
||
docker system prune -a
|
||
|
||
# Build cache'i temizle
|
||
docker builder prune
|
||
```
|
||
|
||
---
|
||
|
||
## 📊 Monitoring
|
||
|
||
### Container İstatistikleri
|
||
|
||
```bash
|
||
# Gerçek zamanlı resource kullanımı
|
||
docker stats
|
||
|
||
# Belirli container'lar için
|
||
docker stats oltalama-backend oltalama-frontend
|
||
```
|
||
|
||
### Log Yönetimi
|
||
|
||
```bash
|
||
# 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](https://docs.docker.com/)
|
||
- [Docker Compose Documentation](https://docs.docker.com/compose/)
|
||
- [Best Practices for Node.js in Docker](https://github.com/nodejs/docker-node/blob/main/docs/BestPractices.md)
|
||
|
||
---
|
||
|
||
## 🆘 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!**
|
||
|