Kapsamlı Proje Kurulum Şablonu: Adım Adım Rehber

froxy · 15 Ağu 2025

Giriş
Bu şablon, yeni bir yazılım projesinin kurulum sürecini sistematik bir şekilde belgelendirmek için hazırlanmıştır. Amacımız, geliştirme ekibinin projeye hızlı ve hatasız bir şekilde adapte olmasını sağlamak, olası kurulum sorunlarını minimize etmek ve standart bir başlangıç noktası sunmaktır. Bu rehber, projenin başarılı bir şekilde yerel geliştirme ortamınızda çalışır duruma gelmesi için gerekli tüm adımları içermektedir. Hem deneyimli geliştiriciler hem de projeye yeni katılanlar için kapsamlı bir başvuru kaynağı olmayı hedeflemektedir. Projelerin karmaşıklığına göre bu şablon özelleştirilebilir.

"İyi belgelenmiş bir kurulum süreci, projenin hayati bir parçasıdır ve zaman kazandırır."

1. Proje Tanımı ve Kapsamı
Projeye başlamadan önce, projenin ne olduğu, neyi hedeflediği ve hangi modülleri içerdiği hakkında net bir anlayışa sahip olmak kritik öneme sahiptir. Bu bölüm, projenin genel yapısını ve amaçlarını özetler.

Proje Adı: Örnek Proje Yönetim Sistemi
Kısa Açıklama: Projelerin planlanması, takibi ve raporlanması için tasarlanmış web tabanlı bir uygulama.
Teknolojiler: Backend: Node.js, Express.js, MongoDB. Frontend: React, Redux. Diğer: Docker, Nginx.
Amaç: Proje yönetim süreçlerini dijitalleştirmek, ekip içi iletişimi artırmak ve verimliliği yükseltmek.
Kapsam Dışı: Örneğin mobil uygulama geliştirme ilk fazda kapsam dışıdır.

Bu detaylar, geliştiricinin projeye başlamadan önce genel bir fikir edinmesini sağlar ve yanlış beklentileri engeller.

2. Gereksinimler
Projenin sorunsuz çalışabilmesi için gerekli olan yazılım ve donanım gereksinimleri bu bölümde listelenir.
2.1. Yazılım Gereksinimleri:

Node.js (LTS Sürümü, örn: v18.x.x)
npm (Node.js ile birlikte gelir) veya Yarn (tercihen)
MongoDB (Community Server, v6.0 veya üzeri)
Docker Desktop (Proje Dockerize edilecekse)
Git (Versiyon kontrolü için)
Tercih Edilen IDE: Visual Studio Code (önerilen eklentilerle birlikte)
Tarayıcı: Google Chrome (geliştirici araçları için)

2.2. Donanım Gereksinimleri:

Minimum 8GB RAM (16GB veya üzeri önerilir)
En az 256GB SSD depolama alanı (512GB veya üzeri önerilir)
Çok çekirdekli işlemci (Intel i5/Ryzen 5 veya üzeri önerilir)
Yeterli ağ bağlantısı (internet erişimi)

Bu gereksinimlerin karşılandığından emin olmak, kurulum sürecinde yaşanabilecek çoğu hatayı baştan engeller.

3. Kurulum Adımları
Bu bölüm, projenin yerel geliştirme ortamınıza nasıl kurulacağına dair adım adım bir rehber sunar.
3.1. Ön Hazırlıklar:

Git Kurulumu: Eğer sisteminizde Git yüklü değilse, resmi web sitesinden indirip kurun: https://git-scm.com/downloads
Node.js ve npm/Yarn Kurulumu: Node.js resmi sitesinden LTS sürümünü indirin: https://nodejs.org/en/download/. Yarn kullanacaksanız, https://classic.yarnpkg.com/lang/en/docs/install/ adresinden kurulum talimatlarını takip edin.
MongoDB Kurulumu: MongoDB Community Server'ı resmi sitesinden indirin ve kurun: https://www.mongodb.com/try/download/community. Kurulum sırasında MongoDB Compass'ı da kurmanız tavsiye edilir.
Docker Desktop Kurulumu (isteğe bağlı ama önerilir): Eğer proje Dockerize edilmişse, Docker Desktop'ı kurmanız gerekecektir: https://www.docker.com/products/docker-desktop/

3.2. Projeyi Klonlama:
Terminalinizi açın ve projeyi klonlamak istediğiniz dizine gidin. Ardından aşağıdaki komutu çalıştırın:

Kod:

git clone https://github.com/ornek/proje-repo.git
cd proje-repo

3.3. Bağımlılıkların Kurulumu:
Projenin hem backend hem de frontend bağımlılıklarını kurmanız gerekmektedir.
Backend Bağımlılıkları:

Kod:

cd backend
npm install   // veya yarn install

Frontend Bağımlılıkları:

Kod:

cd ../frontend
npm install   // veya yarn install

3.4. Veritabanı Kurulumu ve Başlatma:
Öncelikle MongoDB sunucusunun çalıştığından emin olun. Eğer manuel olarak başlatmanız gerekiyorsa:

Kod:

// Windows
"C:\Program Files\MongoDB\Server\6.0\bin\mongod.exe" --dbpath="C:\data\db"

// macOS/Linux
sudo systemctl start mongod  // veya mongod --dbpath /data/db

Projenin veritabanı şemasını oluşturmak ve başlangıç verilerini yüklemek için:

Kod:

cd ../backend
npm run setup-db  // veya proje özel script'i

Bu adım, projenin varsayılan veritabanı yapısını ve gerekli başlangıç verilerini oluşturur.

3.5. Projeyi Başlatma:
Tüm bağımlılıklar yüklendikten ve veritabanı hazırlandıktan sonra projeyi başlatabilirsiniz.
Backend'i Başlatma:
Ayrı bir terminal penceresinde:

Kod:

cd backend
npm start  // veya nodemon index.js

Frontend'i Başlatma:
Başka bir terminal penceresinde:

Kod:

cd frontend
npm start  // veya yarn start

Proje varsayılan olarak http://localhost:3000 (frontend) ve http://localhost:5000 (backend API) adreslerinde erişilebilir olacaktır.

4. Yapılandırma
Projenin çeşitli ortamlarda (geliştirme, test, üretim) farklı çalışması için yapılandırma dosyaları kullanılır. Genellikle `.env` dosyaları tercih edilir.

`.env` Dosyası: Proje ana dizininde veya ilgili modül dizinlerinde (`backend/.env`, `frontend/.env`) bir `.env` dosyası oluşturmanız gerekebilir. Örnek bir `.env.example` dosyası varsa, onu kopyalayıp gerekli çevre değişkenlerini ayarlayın.
Kod:
```
DB_URI=mongodb://localhost:27017/proje_db
PORT=5000
NODE_ENV=development
JWT_SECRET=gizliAnahtar123
```
Bu değerleri kendi ortamınıza ve güvenlik gereksinimlerinize göre ayarlayın.
API Uç Noktaları: Frontend uygulamasının backend API'ye doğru adresten ulaştığından emin olun. Geliştirme ortamında genellikle http://localhost:5000 gibi yerel adresler kullanılır.

Yapılandırma hataları, uygulamanın beklenmedik şekilde davranmasına veya hiç çalışmamasına neden olabilir, bu yüzden bu bölüm dikkatlice kontrol edilmelidir.

5. Test ve Doğrulama
Kurulumun başarılı olduğunu doğrulamak için aşağıdaki testleri yapın:

Tarayıcınızda http://localhost:3000 adresine gidin ve frontend uygulamasının ana sayfasının yüklendiğini kontrol edin.
Uygulama üzerindeki temel işlevleri (örn. kullanıcı kaydı, giriş yapma, basit bir veri listeleme) test edin.
Backend API uç noktalarına Postman veya tarayıcı üzerinden manuel istekler göndererek doğru yanıtlar alıp almadığınızı kontrol edin (örn. http://localhost:5000/api/status).
Varsa, birim ve entegrasyon testlerini çalıştırın:
Kod:
```
cd backend
npm test

cd ../frontend
npm test
```

Bu testler, projenin temel bileşenlerinin beklenen şekilde çalışıp çalışmadığını anlamanıza yardımcı olacaktır.

6. Sıkça Sorulan Sorular ve Sorun Giderme

Soru: `npm install` komutu çalışmıyor veya bağımlılık hataları veriyor.
Cevap: Node.js ve npm/Yarn sürümlerinizin uyumlu olduğundan emin olun. `npm cache clean --force` komutunu çalıştırıp tekrar deneyin. Bazen `node_modules` klasörünü ve `package-lock.json` dosyasını silip yeniden `npm install` yapmak sorunu çözebilir.
Soru: MongoDB bağlantı hatası alıyorum.
Cevap: MongoDB sunucusunun çalıştığından ve doğru port üzerinden erişilebilir olduğundan emin olun (varsayılan 27017). Güvenlik duvarı ayarlarınızı kontrol edin. `DB_URI` değişkeninin `.env` dosyasında doğru olduğundan emin olun.
Soru: Frontend uygulaması backend'e bağlanamıyor.
Cevap: Backend sunucusunun çalıştığından ve doğru portta (örn. 5000) dinlediğinden emin olun. Frontend uygulamasındaki API URL'lerinin doğru yapılandırıldığını kontrol edin. Çapraz kaynak (CORS) sorunları yaşıyorsanız, backend uygulamanızın CORS ayarlarını gözden geçirin.
Soru: Proje başlatılırken belirli bir dosya bulunamadı hatası alıyorum.
Cevap: Proje dizininde olup olmadığınızı ve gerekli dosyaların mevcut olup olmadığını kontrol edin. Git klonlaması sırasında bir hata oluşmuş olabilir veya eksik dosya indirilmiş olabilir. Tekrar klonlamayı deneyin.

Bu bölümde sık karşılaşılan sorunlar ve olası çözümleri listelenmiştir. Daha karmaşık sorunlar için projenin genel destek kanallarını kullanın.

7. İletişim ve Destek
Kurulum sürecinde veya sonrasında karşılaştığınız sorunlar için aşağıdaki kanalları kullanabilirsiniz:

Proje Yöneticisi: proje.yonetici@ornek.com
Teknik Destek: destek@ornek.com
Slack Kanalı: #ornek-proje-destek
Git Deposu Sorunlar (Issues) Sayfası: https://github.com/ornek/proje-repo/issues

Lütfen sorunlarınızı mümkün olduğunca detaylı açıklayın ve karşılaştığınız hata mesajlarını eklemeyi unutmayın.

Sonuç
Bu kapsamlı proje kurulum şablonu, yeni geliştiricilerin projeye kolayca adapte olmasını sağlamak ve ortak bir başlangıç noktası oluşturmak için tasarlanmıştır. Belgelendirme, başarılı bir projenin temelidir. Bu rehberi takip ederek, yerel geliştirme ortamınızı sorunsuz bir şekilde kurabilir ve hızla kod yazmaya başlayabilirsiniz. Bu şablonun, projenizin yaşam döngüsü boyunca güncel tutulması ve geliştirilmesi büyük önem taşımaktadır. Herhangi bir eksiklik veya iyileştirme öneriniz varsa lütfen ilgili kişilere bildirin. Başarılar dileriz!