wisecolt
0961751f4d
UI ve dokümantasyon boyunca "Job" terimleri "Test" olarak değiştirildi. Bu değişiklik, uygulamanın terminolojisini tutarlı hale getirmek ve kullanıcı arayüzünde daha doğru bir isimlendirme sağlamak için yapıldı. Tüm etiketler, başlıklar, bildirimler ve dokümantasyon güncellendi.
445 lines
15 KiB
Markdown
445 lines
15 KiB
Markdown
# Wisecolt CI 🚀
|
||
|
||
**Modern CI/CD Platformu - Repository otomasyonu ve test süreçleri için tasarlanmış tam teşekküllü web uygulaması**
|
||
|
||
    
|
||
|
||
## 📋 İçindekiler
|
||
|
||
- [✨ Özellikler](#-zellikler)
|
||
- [🛠 Teknoloji Yığını](#-teknoloji-yığını)
|
||
- [📁 Proje Yapısı](#-proje-yapısı)
|
||
- [🚀 Kurulum](#-kurulum)
|
||
- [🎯 Kullanım](#-kullanım)
|
||
- [📚 Dökümantasyon](#-dokümantasyon)
|
||
- [🧪 Geliştirme](#-geliştirme)
|
||
|
||
## ✨ Özellikler
|
||
|
||
### 🔐 Güvenli Kimlik Yönetimi
|
||
- **JWT Tabanlı Authentication**: Modern ve güvenli token tabanlı kimlik doğrulama
|
||
- **Korumalı Endpoint'ler**: JWT middleware ile korunan API endpoint'leri
|
||
- **Environment Security**: Hassas bilgilerin güvenli .env dosyasında saklanması
|
||
|
||
### 🧪 Test Yönetim Sistemi
|
||
- **Repository Otomasyonu**: Otomatik git clone/pull işlemleri
|
||
- **Zaman Tabanlı Çalıştırma**: Dakika/saat/gün bazında otomatik test çalıştırma
|
||
- **Real-time Durum Güncellemesi**: Socket.io ile anlık durum takibi
|
||
- **Test Sonuçları**: Başarılı/başarısız sonuçların kaydedilmesi
|
||
- **Log Akışı**: Gerçek zamanlı test loglarının izlenmesi
|
||
|
||
### 🚀 Deployment Yönetimi
|
||
- **Root Tarama**: `DEPLOYMENTS_ROOT_HOST` altında compose dosyası olan projeleri otomatik bulma
|
||
- **Webhook Tetikleme**: Gitea push event ile otomatik deploy
|
||
- **Branch Seçimi**: Repo URL girince branch listesi alınır ve seçim yapılır
|
||
- **Deploy Geçmişi**: Her deploy için log ve süre kaydı
|
||
- **Güvenlik**: API Token + Webhook Secret ile doğrulama
|
||
|
||
### ⚡ Gerçek Zamanlı İletişim
|
||
- **WebSocket Bağlantısı**: Socket.io ile sürekli iletişim
|
||
- **Sayaç Yayınınlaması**: Global sayaç ve işlemler
|
||
- **Canlı Güncellemeler**: Test durumlarının anlık bildirilmesi
|
||
- **Ping/Pong**: Bağlantı kontrolü
|
||
|
||
### 🎨 Modern Arayüz
|
||
- **React 18**: Modern bileşen tabanlı UI kütüphanesi
|
||
- **TypeScript**: Tip güvenli geliştirme deneyimi
|
||
- **Responsive Design**: Mobil uyumlu tasarım
|
||
- **Tema Desteği**: Dark/Light moda geçiş imkanı
|
||
- **Toast Bildirimleri**: Kullanıcı bildirim sistemi
|
||
|
||
## 🛠 Teknoloji Yığını
|
||
|
||
### Backend Stack
|
||
```yaml
|
||
Platform: Node.js 18+
|
||
Framework: Express.js
|
||
Language: TypeScript
|
||
Database: MongoDB
|
||
Authentication: JWT
|
||
Real-time: Socket.io
|
||
Process Manager: Child Process
|
||
ODM: Mongoose
|
||
Dev Tools: tsx (hot-reload)
|
||
```
|
||
|
||
### Frontend Stack
|
||
```yaml
|
||
Platform: React 18
|
||
Language: TypeScript
|
||
Build Tool: Vite
|
||
UI Library: shadcn/ui
|
||
Styling: Tailwind CSS
|
||
HTTP Client: Axios
|
||
Routing: React Router DOM
|
||
Icons: Lucide React + Font Awesome
|
||
Notifications: Sonner
|
||
```
|
||
|
||
### DevOps
|
||
```yaml
|
||
Containerization: Docker
|
||
Orchestration: Docker Compose
|
||
Hot Reload: Backend (tsx) + Frontend (Vite)
|
||
Environment: .env configuration
|
||
Development: Bind mounts for live reload
|
||
```
|
||
|
||
## 📁 Proje Yapısı
|
||
|
||
```
|
||
wisecolt-ci/
|
||
├── 📁 docs/ # 📚 Dökümantasyonlar
|
||
│ ├── PROJE_DOKUMANTASYONU.md # Detaylı proje dokümantasyonu
|
||
│ └── TEKNIK_ANALIZ_RAPORU.md # Teknoloji analizi ve öneriler
|
||
├── 📁 backend/ # ⚙️ Backend uygulaması
|
||
│ ├── src/
|
||
│ │ ├── 📁 config/ # Konfigürasyon yönetimi
|
||
│ │ │ └── env.ts
|
||
│ │ ├── 📁 middleware/ # Express middleware'leri
|
||
│ │ │ └── authMiddleware.ts
|
||
│ │ ├── 📁 models/ # MongoDB modelleri
|
||
│ │ │ ├── job.ts
|
||
│ │ │ ├── deploymentProject.ts
|
||
│ │ │ ├── deploymentRun.ts
|
||
│ │ │ └── settings.ts
|
||
│ │ ├── 📁 routes/ # API route'ları
|
||
│ │ │ ├── auth.ts
|
||
│ │ │ ├── jobs.ts
|
||
│ │ │ ├── deployments.ts
|
||
│ │ │ └── webhooks.ts
|
||
│ │ ├── 📁 services/ # İş mantığı katmanı
|
||
│ │ │ └── jobService.ts
|
||
│ │ └── 📄 index.ts # Ana sunucu dosyası
|
||
│ ├── 📄 package.json
|
||
│ ├── 📄 tsconfig.json
|
||
│ ├── 🐳 Dockerfile
|
||
│ └── 📝 .env.example
|
||
├── 📁 frontend/ # 🎨 Frontend uygulaması
|
||
│ ├── src/
|
||
│ │ ├── 📁 api/ # API client katmanı
|
||
│ │ │ └── client.ts
|
||
│ │ ├── 📁 components/ # UI bileşenleri
|
||
│ │ │ ├── 📁 ui/ # shadcn/ui bileşenleri
|
||
│ │ │ │ ├── button.tsx
|
||
│ │ │ │ ├── card.tsx
|
||
│ │ │ │ ├── input.tsx
|
||
│ │ │ │ ├── select.tsx
|
||
│ │ │ │ └── ...
|
||
│ │ │ ├── ProtectedRoute.tsx
|
||
│ │ │ ├── DashboardLayout.tsx
|
||
│ │ │ └── ThemeToggle.tsx
|
||
│ │ ├── 📁 pages/ # Sayfa bileşenleri
|
||
│ │ │ ├── HomePage.tsx
|
||
│ │ │ ├── JobsPage.tsx
|
||
│ │ │ ├── JobDetailPage.tsx
|
||
│ │ │ ├── DeploymentsPage.tsx
|
||
│ │ │ ├── DeploymentDetailPage.tsx
|
||
│ │ │ └── SettingsPage.tsx
|
||
│ │ ├── 📁 providers/ # React Context Provider'lar
|
||
│ │ │ ├── auth-provider.tsx
|
||
│ │ │ ├── socket-provider.tsx
|
||
│ │ │ ├── live-provider.tsx
|
||
│ │ │ └── theme-provider.tsx
|
||
│ │ ├── 📄 App.tsx # Ana uygulama bileşeni
|
||
│ │ └── 📄 main.tsx # Giriş noktası
|
||
│ ├── 📄 package.json
|
||
│ ├── 📄 vite.config.ts
|
||
│ ├── 🎨 tailwind.config.js
|
||
│ ├── 🐳 Dockerfile
|
||
│ └── 📝 .env.example
|
||
├── 🐳 docker-compose.yml # 🐳 Konteyner orkestrasyonu
|
||
├── 📄 README.md # 📋 Proje ana sayfası
|
||
├── 📄 .gitignore # Git ignore kuralları
|
||
└── 📝 .env.example # Ortam değişkenleri örneği
|
||
```
|
||
|
||
## 🚀 Kurulum
|
||
|
||
### Gereksinimler
|
||
- **Docker** ve **Docker Compose**
|
||
- **Git** (repository klonlama için)
|
||
|
||
### 1. Repository Klonlama
|
||
```bash
|
||
git clone https://github.com/kullanici/wisecolt-ci.git
|
||
cd wisecolt-ci
|
||
```
|
||
|
||
### 2. Ortam Değişkenlerini Ayarlama
|
||
```bash
|
||
# Backend konfigürasyonu
|
||
cp backend/.env.example backend/.env
|
||
|
||
# Frontend konfigürasyonu
|
||
cp frontend/.env.example frontend/.env
|
||
|
||
# Admin bilgilerini güvenli şekilde girin
|
||
# backend/.env dosyasını düzenleyin
|
||
```
|
||
|
||
### 3. Servisleri Başlatma
|
||
```bash
|
||
# Tüm servisleri build edip başlatma
|
||
docker compose up --build
|
||
|
||
# Arka planda çalıştırma
|
||
docker compose up -d --build
|
||
```
|
||
|
||
### 4. Uygulamaya Erişim
|
||
- **Frontend**: http://localhost:5173
|
||
- **Backend API**: http://localhost:4000
|
||
- **MongoDB**: mongodb://localhost:27017
|
||
- **Health Check**: http://localhost:4000/health
|
||
|
||
## 🎯 Kullanım
|
||
|
||
### Giriş İşlemi
|
||
1. Tarayıcıda http://localhost:5173 adresine gidin
|
||
2. Varsayılan giriş bilgileri:
|
||
- **Kullanıcı Adı**: `admin`
|
||
- **Şifre**: `supersecret`
|
||
3. Giriş yap butonuna tıklayın
|
||
|
||
### Test Yönetimi
|
||
|
||
#### Yeni Test Oluşturma
|
||
1. **Dashboard** menüsünden **Tests** sayfasına gidin
|
||
2. **Yeni Test** butonuna tıklayın
|
||
3. Test bilgilerini girin:
|
||
- **Test Adı**: Tanımlayıcı bir isim
|
||
- **Repository URL**: GitHub repository adresi
|
||
- **Test Komutu**: Çalıştırılacak komut (örn: `npm test`)
|
||
- **Kontrol Aralığı**: Test sıklığı (dakika/saat/gün)
|
||
- **Kontrol Değeri**: Sayısal değer
|
||
4. Kaydet butonuna tıklayın
|
||
|
||
#### Test İzleme
|
||
- **Tests Listesi**: Tüm test'lerin durumunu gösterir
|
||
- **Real-time Durum**: Socket.io ile anlık güncellemeler
|
||
- **Log Akışı**: Test çıktılarını canlı izleme
|
||
- **Manuel Çalıştırma**: Test'i anında tetikleme
|
||
|
||
### Deployment Yönetimi
|
||
1. **Deployments** sayfasına gidin
|
||
2. **New Deployment** ile root altında taranan projeyi seçin
|
||
3. Repo URL + Branch + Compose dosyasını girin
|
||
4. Kaydettikten sonra **Webhook URL**’i Gitea’da web istemci olarak tanımlayın
|
||
|
||
#### Webhook Ayarları (Gitea)
|
||
- **Hedef URL**: `https://<domain>/api/deployments/webhook/<token>`
|
||
- **Yetkilendirme Başlığı**: `Bearer <API_TOKEN>`
|
||
- **Gizli**: `WEBHOOK_SECRET`
|
||
- **HTTP Yöntemi**: `POST`
|
||
- **İçerik Türü**: `application/json`
|
||
|
||
### Authentication
|
||
|
||
#### Token Yönetimi
|
||
- **Otomatik Login**: Başarılı girişte JWT token oluşturulur
|
||
- **Token Saklama**: localStorage'da güvenli saklama
|
||
- **Otomatik Yenileme**: Sayfa yenilemede token kontrolü
|
||
- **Korumalı Yönlendirme**: Token olmadığında login sayfası
|
||
|
||
## 📚 Dökümantasyon
|
||
|
||
### 📄 Detaylı Dökümantasyonlar
|
||
- **[PROJE_DOKUMANTASYONU.md](docs/PROJE_DOKUMANTASYONU.md)** - Kapsamlı proje dokümantasyonu
|
||
- **[TEKNIK_ANALIZ_RAPORU.md](docs/TEKNIK_ANALIZ_RAPORU.md)** - Teknoloji analizi ve öneriler
|
||
|
||
### 📖 API Referansı
|
||
- **Authentication API'leri**: `/auth/login`, `/auth/me`
|
||
- **Test Yönetim API'leri**: CRUD operasyonları, manuel çalıştırma
|
||
- **Deployment API'leri**: `/deployments`, `/deployments/:id`, `/deployments/scan`, `/deployments/branches`
|
||
- **Webhook Endpoint**: `/api/deployments/webhook/:token`
|
||
- **WebSocket Olayları**: Real-time iletişim ve durum güncellemeleri
|
||
- **Endpoint Detayları**: Her endpoint için istek/yanıt formatları
|
||
|
||
### 🏗 Mimari Dokümantasyonu
|
||
- **Backend Mimarisi**: Express.js + TypeScript + MongoDB
|
||
- **Frontend Mimarisi**: React 18 + Vite + shadcn/ui
|
||
- **Socket.io İletişimi**: WebSocket olayları ve yönetimi
|
||
- **Veritabanı Tasarımı**: MongoDB schema ve indeksleme
|
||
|
||
## 🧪 Geliştirme
|
||
|
||
### Geliştirme Ortamı Kurulumu
|
||
```bash
|
||
# Repository klonlama
|
||
git clone https://github.com/kullanici/wisecolt-ci.git
|
||
cd wisecolt-ci
|
||
|
||
# Backend bağımlılıkları
|
||
cd backend
|
||
npm install
|
||
|
||
# Frontend bağımlılıkları
|
||
cd ../frontend
|
||
npm install
|
||
|
||
# Servisleri başlatma
|
||
docker compose up --build
|
||
```
|
||
|
||
### Hot Reload Özellikleri
|
||
- **Backend**: `tsx watch src/index.ts` - TypeScript derlemesi ve sunucu yeniden başlatma
|
||
- **Frontend**: Vite dev server - Hızlı modül değişiklikleri ve tarayıcı yenilemesi
|
||
- **Docker Bind Mounts**: Kod değişikliklerinin konteynerde anlık yansıması
|
||
|
||
### API Geliştirme
|
||
```typescript
|
||
// Yeni route ekleme
|
||
import { Router } from 'express';
|
||
import { authMiddleware } from '../middleware/authMiddleware';
|
||
|
||
const router = Router();
|
||
router.use(authMiddleware);
|
||
|
||
router.get('/endpoint', (req, res) => {
|
||
res.json({ message: 'API çalışıyor' });
|
||
});
|
||
|
||
export default router;
|
||
```
|
||
|
||
### Frontend Geliştirme
|
||
```typescript
|
||
// Yeni bileşen oluşturma
|
||
import React from 'react';
|
||
|
||
const YeniBilesen = () => {
|
||
return (
|
||
<div className="p-4">
|
||
<h1>Yeni Bileşen</h1>
|
||
<p>Bileşen içeriği</p>
|
||
</div>
|
||
);
|
||
};
|
||
|
||
export default YeniBilesen;
|
||
```
|
||
|
||
### Test Çalıştırma
|
||
```bash
|
||
# Backend testleri
|
||
cd backend
|
||
npm test
|
||
|
||
# Frontend testleri
|
||
cd frontend
|
||
npm test
|
||
```
|
||
|
||
### Kod Standartları
|
||
- **TypeScript**: Strict typing ve interface kullanımı
|
||
- **ESLint**: Kod kalite kontrolü
|
||
- **Prettier**: Kod formatlama
|
||
- **Git Hooks**: Pre-commit validation'ları
|
||
|
||
## 🔧 Konfigürasyon
|
||
|
||
### Environment Değişkenleri
|
||
```bash
|
||
# Backend (.env)
|
||
PORT=4000 # Backend sunucu portu
|
||
MONGO_URI=mongodb://mongo:27017/wisecoltci # MongoDB bağlantı adresi
|
||
ADMIN_USERNAME=admin # Admin kullanıcı adı
|
||
ADMIN_PASSWORD=supersecret # Admin şifresi
|
||
JWT_SECRET=gizli-jwt-anahtari # JWT imzalama anahtarı
|
||
CLIENT_ORIGIN=http://localhost:5173 # Frontend adresi (CORS için)
|
||
|
||
# Docker Compose (.env)
|
||
DEPLOYMENTS_ROOT_HOST=/home/wisecolt-dev/workspace # Zorunlu: host proje dizini
|
||
|
||
# Frontend (.env)
|
||
VITE_API_URL=http://localhost:4000/api # Backend API adresi
|
||
```
|
||
|
||
### Port Yapılandırması
|
||
| Servis | Port | Açıklama |
|
||
|--------|------|------------|
|
||
| Frontend | 5173 | Vite dev server |
|
||
| Backend | 4000 | Express API sunucusu |
|
||
| MongoDB | 27017 | Veritabanı servisi |
|
||
|
||
## 🚨 Hata Ayıklama
|
||
|
||
### Common Issues
|
||
1. **Port Çakışması**: Portların kullanımda olup olmadığını kontrol edin
|
||
2. **MongoDB Bağlantı Hatası**: Docker servisinin çalıştığından emin olun
|
||
3. **CORS Hatası**: CLIENT_ORIGIN ayarını kontrol edin
|
||
4. **JWT Hatası**: Token süresi dolmuş olabilir
|
||
|
||
### Log Kontrolü
|
||
```bash
|
||
# Docker konteyner logları
|
||
docker compose logs backend
|
||
docker compose logs frontend
|
||
docker compose logs mongo
|
||
|
||
# Real-time loglar
|
||
# Browser developer tools > Console
|
||
# Socket.io events için network tab
|
||
```
|
||
|
||
### Performans Optimizasyonu
|
||
- **Database İndeksleme**: Sık sorgulanan alanlar için indeksler
|
||
- **Frontend Bundle**: Vite build optimizasyonu
|
||
- **Caching**: MongoDB ve Redis cache stratejileri
|
||
- **Code Splitting**: Lazy loading implementasyonu
|
||
|
||
## 📈 Vizyon ve Yol Haritası
|
||
|
||
### Mevcut Durum (v1.0)
|
||
- ✅ Temel CI/CD platformu
|
||
- ✅ Real-time test yönetimi
|
||
- ✅ Modern web arayüzü
|
||
- ✅ Konteyner orkestrasyonu
|
||
|
||
### Gelecek Planlar
|
||
- 🔄 **Multi-branch Support**: Farklı branch'ler için test yönetimi
|
||
- 🔔 **Bildirim Sistemi**: E-posta ve Slack bildirimleri
|
||
- 📊 **Dashboard İstatistikleri**: Performans ve kullanım metrikleri
|
||
- 🛡️ **Güvenlik İyileştirmeleri**: 2FA ve rate limiting
|
||
- 🌐 **Multi-cloud Support**: AWS, GCP, Azure entegrasyonu
|
||
- 📝 **Custom Test Commands**: Esnek test komutu yapılandırması
|
||
|
||
### E-post Listesi
|
||
- 📊 **Dashboard İstatistikleri**: Test performans grafikleri
|
||
- 🔔 **Bildirim Kanalları**: Slack, Discord, Teams entegrasyonu
|
||
- 🔄 **Pipeline Integration**: GitHub Actions, GitLab CI entegrasyonu
|
||
- 🏗️ **Template System**: Hazır proje şablonları
|
||
- 🌐 **Cloud Provider Filtreleri**: AWS CodeDeploy, Vercel, Netlify
|
||
|
||
## 🤝 Katkı ve Destek
|
||
|
||
### Katkıda Bulunma
|
||
1. **Repository'i Forklayın**: GitHub'da fork oluşturun
|
||
2. **Feature Branch**: `feature/ozellik-adi` formatında branch oluşturun
|
||
3. **Pull Request**: Değişiklikleri ana branch'e gönderin
|
||
4. **Test**: Tüm testlerin geçtiğinden emin olun
|
||
5. **Dokümantasyon**: Değişiklikleri belgelendirin
|
||
|
||
### Hata Bildirimi
|
||
- **GitHub Issues**: [github.com/proje/issues](https://github.com/proje/issues)
|
||
- **Feature İstekleri**: [github.com/proje/discussions](https://github.com/proje/discussions)
|
||
- **Soru ve Yardım**: Discord veya GitHub Discussions
|
||
|
||
### Lisans
|
||
Bu proje MIT lisansı altında dağıtılmaktadır. Detaylı bilgi için [LICENSE](LICENSE) dosyasını inceleyin.
|
||
|
||
---
|
||
|
||
## 🌟 Teşekkürler
|
||
|
||
Bu projeye katkı sağlayan tüm geliştiricilere ve açık kaynak kütüphanelerine teşekkür ederiz. Özelliklele:
|
||
|
||
- **React Team** - Modern UI kütüphanesi için
|
||
- **Vite Team** - Hızlı build tool için
|
||
- **shadcn/ui** - Modern bileşen kütüphanesi için
|
||
- **MongoDB Team** - Esnek veritabanı için
|
||
- **Socket.io** - Gerçek zamanlı iletişim için
|
||
|
||
**Wisecolt-CI** - **Repository otomasyonu, basitleştirilmiş! 🚀**
|