wisecolt/Wisecolt-CI
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
945c0e7a76f01979359006c7f3aa642f04889ff6
Wisecolt-CI/docs/PROJE_DOKUMANTASYONU.md

13 KiB
Raw Blame History

Wisecolt-CI Proje Dökümantasyonu

📋 İçindekiler

🎯 Proje Genel Bakış

Wisecolt-CI, modern web teknolojileriyle geliştirilmiş tam teşekküllü bir CI/CD (Sürekli Entegrasyon/Sürekli Dağıtım) platformudur. Proje, repository otomasyonu ve test süreçlerini yönetmek için tasarlanmıştır.

✨ Temel Özellikler

  • 🔐 Kimlik Doğrulama: JWT tabanlı güvenli kimlik yönetimi
  • 📊 Job Yönetimi: Repository'lar için otomatik test süreçleri
  • ⚡ Gerçek Zamanlı: Socket.io ile canlı durum güncellemeleri
  • 🎨 Modern UI: React + shadcn/ui ile responsive arayüz
  • 🌙 Tema Desteği: Dark/Light moda geçiş imkanı
  • 🐳 Konteynerizasyon: Docker ile tam izole geliştirme ortamı

🛠 Teknoloji Yığını

Backend

  • Node.js + TypeScript - Güçlü sunucu tarafı geliştirme
  • Express.js - Minimal ve esnek web framework'ü
  • MongoDB - NoSQL veritabanı
  • Socket.io - Gerçek zamanlı çift yönlü iletişim
  • JWT - Güvenli kimlik doğrulama
  • Mongoose - MongoDB modelleme ve validasyon

Frontend

  • React 18 - Modern bileşen tabanlı UI kütüphanesi
  • TypeScript - Tip güvenli geliştirme
  • Vite - Hızlı build tool ve geliştirme sunucusu
  • Tailwind CSS - Utility-first CSS framework'ü
  • shadcn/ui - Modern React UI bileşen kütüphanesi
  • React Router - Client tarafı rotalama
  • Axios - HTTP istemci kütüphanesi

DevOps

  • Docker + Docker Compose - Konteyner orkestrasyon
  • Hot Reload - Geliştirme anında canlı güncellemeler

📊 Backend Dökümantasyonu

🏗 Mimari

Backend, RESTful API prensiplerine göre tasarlanmış modüler bir yapıya sahiptir.

Ana Bileşenler

  1. Express Sunucusu (src/index.ts)
  2. Router'lar (src/routes/)
  3. Middleware (src/middleware/)
  4. Servisler (src/services/)
  5. Modeller (src/models/)
  6. Konfigürasyon (src/config/)

🔐 Authentication Sistemi

Endpoint'ler

  • POST /auth/login - Kullanıcı girişi
  • GET /auth/me - Token doğrulama ve kullanıcı bilgileri

Güvenlik Özellikleri

  • JWT tabanlı kimlik doğrulama
  • Bearer token authentication
  • CORS yapılandırması
  • .env tabanlı hassas bilgi yönetimi

Kullanım

// Giriş işlemi
const response = await fetch('/auth/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ username, password })
});

// Token ile korumalı istek
const response = await fetch('/protected-endpoint', {
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  }
});

📋 Job Yönetim Sistemi

Model Yapısı

interface JobDocument {
  name: string;           // Job adı
  repoUrl: string;        // Repository URL'si
  testCommand: string;    // Çalıştırılacak test komutu
  checkValue: number;      // Kontrol değeri (dakika/saat/gün)
  checkUnit: TimeUnit;    // Kontrol birimi
  status: JobStatus;     // Job durumu
  lastRunAt?: Date;      // Son çalışma zamanı
  lastDurationMs?: number; // Son çalışma süresi (ms)
  lastMessage?: string;   // Son mesaj
}

Endpoint'ler

  • GET /jobs - Tüm job'ları listele
  • GET /jobs/:id - Job detaylarını getir
  • POST /jobs - Yeni job oluştur
  • PUT /jobs/:id - Job güncelle
  • DELETE /jobs/:id - Job sil
  • POST /jobs/:id/run - Job'ı manuel çalıştır

Job Süreç Yönetimi

  • Otomatik Çalıştırma: Belirlenen aralıklarla otomatik çalışma
  • Git Operasyonları: Clone/pull işlemleri
  • NPM Kurulum: Bağımlılıkların otomatik kurulumu
  • Test Çalıştırma: Belirlenen komutların çalıştırılması
  • Sonuç Kaydı: Test sonuçlarının veritabanına kaydedilmesi

⚡ Socket.io Real-time İletişim

Olaylar

  • connection - Yeni bağlantı kurulduğunda
  • hello - Bağlantı kurulduğunda hoş geldik mesajı
  • ping/pong - Bağlantı kontrolü
  • counter:update - Sayaç güncellemesi
  • counter:start/stop - Sayaç başlatma/durdurma
  • job:subscribe - Job durum takibi
  • job:status - Job durum güncellemesi
  • job:log - Job log akışı

Kullanım Örneği

// Client tarafı
socket.on('job:status', (data) => {
  console.log('Job durumu güncellendi:', data);
});

// Server tarafı
io.to(`job:${jobId}`).emit('job:status', {
  jobId,
  status: 'running',
  lastMessage: 'Test çalıştırılıyor...'
});

🔧 Konfigürasyon Yönetimi

Environment Değişkenleri

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=your-secret-key            # JWT imzalama anahtarı
CLIENT_ORIGIN=http://localhost:5173    # Frontend adresi (CORS için)

🎨 Frontend Dökümantasyonu

🏗 Mimari

Frontend, modern React prensiplerine göre tasarlanmış bileşen tabanlı bir yapıya sahiptir.

Ana Bileşenler

  1. App Component - Ana rotalama ve yapılandırma
  2. Pages - Sayfa bileşenleri (HomePage, JobsPage, vb.)
  3. Components - Yeniden kullanılabilir UI bileşenleri
  4. Providers - React Context Provider'lar
  5. API Layer - Backend ile iletişim katmanı

🔐 Authentication Provider

AuthProvider Özellikleri

  • Kullanıcı durum yönetimi
  • Token saklama (localStorage)
  • Otomatik kimlik doğrulama
  • Login/logout işlemleri

Kullanım

const { user, token, login, logout, loading } = useAuth();

// Giriş yapma
await login('admin', 'password');

// Çıkış yapma
logout();

// Korumalı bileşen
if (!user) {
  return <Navigate to="/login" />;
}

📱 Sayfa Bileşenleri

HomePage

  • Proje genel bakış ve istatistikler
  • Hızlı erişim linkleri

JobsPage

  • Job listesi
  • Job oluşturma/düzenleme/silme işlemleri
  • Real-time durum güncellemeleri

JobDetailPage

  • Job detayları
  • Manuel çalıştırma
  • Log akışı izleme

🎨 UI Bileşen Kütüphanesi (shadcn/ui)

Temel Bileşenler

  • Button - Özelleştirilebilir düğmeler
  • Input - Form giriş alanları
  • Select - Seçim kutuları
  • Card - Kart bileşenleri
  • Label - Etiket bileşenleri
  • Switch - Toggle switch'ler
  • Toaster - Bildirim sistemi

Stil Sistemi

  • Tailwind CSS - Utility-first stil yaklaşımı
  • Responsive Design - Mobil uyumlu tasarım
  • Tema Desteği - Dark/Light moda geçiş

📱 Responsive Tasarım

Breakpoint'ler

  • sm: - 640px ve üzeri
  • md: - 768px ve üzeri
  • lg: - 1024px ve üzeri
  • xl: - 1280px ve üzeri

Örnek Kullanım

<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
  {/* Responsive grid layout */}
</div>

🔌 API Referansı

Authentication API

POST /auth/login

Kullanıcı girişi için endpoint.

Request Body:

{
  "username": "admin",
  "password": "supersecret"
}

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "username": "admin"
}

GET /auth/me

Token doğrulama ve kullanıcı bilgileri.

Headers:

Authorization: Bearer <token>

Response:

{
  "username": "admin"
}

Jobs API

GET /jobs

Tüm job'ları listeler.

Response:

[
  {
    "_id": "64a1b2c3d4e5f6789012345",
    "name": "Frontend Tests",
    "repoUrl": "https://github.com/user/frontend-repo",
    "testCommand": "npm test",
    "checkValue": 5,
    "checkUnit": "dakika",
    "status": "idle",
    "lastRunAt": "2023-07-01T10:30:00.000Z",
    "lastDurationMs": 45000,
    "lastMessage": "Başarılı",
    "createdAt": "2023-07-01T08:00:00.000Z",
    "updatedAt": "2023-07-01T10:30:00.000Z"
  }
]

POST /jobs

Yeni job oluşturur.

Request Body:

{
  "name": "Backend Tests",
  "repoUrl": "https://github.com/user/backend-repo",
  "testCommand": "npm run test",
  "checkValue": 10,
  "checkUnit": "dakika"
}

GET /jobs/:id

Belirtilen job'ın detaylarını getirir.

PUT /jobs/:id

Mevcut job'ı günceller.

Request Body: POST ile aynı formatta

DELETE /jobs/:id

Job'ı siler.

Response:

{
  "success": true
}

POST /jobs/:id/run

Job'ı manuel olarak çalıştırır.

Response:

{
  "queued": true
}

WebSocket Olayları

client → server

  • ping - Bağlantı kontrolü
  • counter:start - Sayaç başlatma
  • counter:stop - Sayaç durdurma
  • counter:status - Sayaç durumu sorgula
  • job:subscribe - Job durum takibi
  • job:unsubscribe - Job durum takibi bırakma

server → client

  • hello - Bağlantı kurulduğunda
  • pong - Ping yanıtı
  • counter:update - Sayaç değeri güncellemesi
  • counter:stopped - Sayaç durduğunda
  • job:status - Job durumu güncellemesi
  • job:log - Job log mesajı

🚀 Kurulum

Gereksinimler

  • Docker ve Docker Compose
  • Git

Adım Adım Kurulum

  1. Repo'yu klonla:
git clone https://github.com/your-repo/wisecolt-ci.git
cd wisecolt-ci
  1. Ortam dosyalarını yapılandır:
cp backend/.env.example backend/.env
cp frontend/.env.example frontend/.env
  1. Admin bilgilerini gir:
# backend/.env
ADMIN_USERNAME=your-admin-username
ADMIN_PASSWORD=your-secure-password
JWT_SECRET=your-jwt-secret-key
CLIENT_ORIGIN=http://localhost:5173

# frontend/.env
VITE_API_URL=http://localhost:4000
  1. Servisleri başlat:
docker compose up --build
  1. Uygulamaya eriş:

💻 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

Job Oluşturma

  1. Sol menüden "Jobs" sayfasına gidin
  2. "Yeni Job" butonuna tıklayın
  3. Job bilgilerini girin:
    • Job Adı: Test için anlaşılır bir ad
    • Repository URL: GitHub repository adresi
    • Test Komutu: Çalıştırılacak komut (örn: npm test)
    • Kontrol Değeri: Kaç dakikada/saat/günde bir çalışacağı
    • Kontrol Birimi: Zaman birimi seçimi
  4. Kaydet butonuna tıklayın

Job İzleme

  1. Jobs sayfasından oluşturduğunuz job'a tıklayın
  2. Job detay sayfasında:
    • Durum: Job'un mevcut durumu (idle/running/success/failed)
    • Sonuçlar: Son çalıştırma sonuçları ve süreleri
    • Loglar: Gerçek zamanlı log akışı
    • Manuel Çalıştırma: Job'u anında çalıştırma

🛠 Geliştirme

Backend Geliştirme

Yeni Route Ekleme

// src/routes/yeniRoute.ts
import { Router } from "express";
import { authMiddleware } from "../middleware/authMiddleware.js";

const router = Router();
router.use(authMiddleware);

router.get("/", (req, res) => {
  res.json({ message: "Yeni endpoint çalışıyor" });
});

export default router;

Ana Dosyada Route Ekleme

// src/index.ts
import yeniRoute from "./routes/yeniRoute.js";

app.use("/yeni", yeniRoute);

Frontend Geliştirme

Yeni Sayfa Ekleme

// src/pages/YeniSayfa.tsx
import React from "react";

export const YeniSayfa = () => {
  return (
    <div>
      <h1>Yeni Sayfa</h1>
      {/* Sayfa içeriği */}
    </div>
  );
};

Rotalama Ekleme

// src/App.tsx
import { YeniSayfa } from "./pages/YeniSayfa";

<Route path="/yeni" element={<YeniSayfa />} />

API İsteği Ekleme

// src/api/client.ts
export async function yeniEndpoint() {
  const { data } = await apiClient.get("/yeni");
  return data;
}

🐳 Docker Yapılandırması

Backend Dockerfile

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
EXPOSE 4000
CMD ["npm", "run", "start"]

Frontend Dockerfile

FROM node:18-alpine as build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM nginx:alpine
COPY --from=build /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/nginx.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

🔄 Otomatik Test Süreci

JobService, belirlenen aralıklarla otomatik test çalıştırır:

  1. Repository Clone: İlk çalıştırmada repo klonlanır
  2. Bağımlılık Kurulum: npm install çalıştırılır
  3. Test Çalıştırma: Belirlenen komut çalıştırılır
  4. Sonuç Kayıt: Sonuçlar veritabanına kaydedilir
  5. Real-time Güncelleme: Socket.io ile client bilgilendirilir

📝 Notlar

Güvenlik

  • JWT token'ları güvenli saklayın
  • Environment değişkenlerini .env dosyasında tutun
  • Production ortamında varsayılan şifreleri değiştirin

Performans

  • MongoDB index'leri kullanın
  • Büyük repository'ler için caching stratejileri uygulayın
  • Frontend build optimizasyonu yapın

İzleme

  • MongoDB log'larını izleyin
  • Docker container log'larını kontrol edin
  • Application metriklerini toplayın

Bu dökümantasyon Wisecolt-CI projesinin tüm özelliklerini ve kullanımını kapsamaktadır. Geliştirme sürecinde güncel tutulmalıdır.

Reference in New Issue View Git Blame Copy Permalink