first commit
This commit is contained in:
Beyhan Oğur
323
README.md
Normal file
323
README.md
Normal file
@@ -0,0 +1,323 @@
|
||||
# Django REST API - Authentication System
|
||||
|
||||
Django 6.0 tabanlı, email authentication, JWT tokens ve social login desteği olan modern bir REST API.
|
||||
|
||||
## 🚀 Özellikler
|
||||
|
||||
- ✅ **Email-based Authentication** (username yok)
|
||||
- ✅ **JWT Tokens** (access + refresh)
|
||||
- ✅ **Email Activation** (kayıt sonrası aktivasyon)
|
||||
- ✅ **Social Login** (Google, GitHub, Facebook)
|
||||
- ✅ **Password Reset** (email ile)
|
||||
- ✅ **Rate Limiting** (güvenlik için)
|
||||
- ✅ **CORS Support** (SPA frontend'ler için)
|
||||
- ✅ **Modern Email Templates** (HTML + plain text)
|
||||
|
||||
## 📋 Gereksinimler
|
||||
|
||||
- Python 3.10+
|
||||
- Django 6.0
|
||||
- PostgreSQL (production) veya SQLite (development)
|
||||
- MailPit (development için email testing)
|
||||
|
||||
## 🛠️ Kurulum
|
||||
|
||||
### 1. Repository'yi Clone'layın
|
||||
```bash
|
||||
git clone <your-repo-url>
|
||||
cd server
|
||||
```
|
||||
|
||||
### 2. Virtual Environment Oluşturun
|
||||
```bash
|
||||
python -m venv .venv
|
||||
source .venv/bin/activate # Linux/Mac
|
||||
# veya
|
||||
.venv\Scripts\activate # Windows
|
||||
```
|
||||
|
||||
### 3. Bağımlılıkları Yükleyin
|
||||
```bash
|
||||
pip install -r req.txt
|
||||
```
|
||||
|
||||
### 4. Environment Variables
|
||||
```bash
|
||||
cp .env.example .env
|
||||
# .env dosyasını düzenleyin
|
||||
```
|
||||
|
||||
### 5. Database Migration
|
||||
```bash
|
||||
python manage.py migrate
|
||||
```
|
||||
|
||||
### 6. Superuser Oluşturun
|
||||
```bash
|
||||
python manage.py createsuperuser
|
||||
```
|
||||
|
||||
### 7. Development Server'ı Başlatın
|
||||
```bash
|
||||
python manage.py runserver
|
||||
```
|
||||
|
||||
API: `http://localhost:8000/api/v1/`
|
||||
Admin: `http://localhost:8000/admin/`
|
||||
|
||||
## 📧 Email Testing (MailPit)
|
||||
|
||||
Development ortamında email'leri test etmek için MailPit kullanıyoruz.
|
||||
|
||||
### MailPit Kurulumu
|
||||
```bash
|
||||
# Docker ile
|
||||
docker run -d -p 1025:1025 -p 8025:8025 axllent/mailpit
|
||||
|
||||
# veya binary ile
|
||||
# https://github.com/axllent/mailpit/releases
|
||||
```
|
||||
|
||||
### MailPit Web UI
|
||||
`http://localhost:8025` - Gönderilen email'leri görüntüleyin
|
||||
|
||||
## 🔐 Authentication Endpoints
|
||||
|
||||
### Register
|
||||
```bash
|
||||
POST /api/v1/auth/users/
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"email": "user@example.com",
|
||||
"password": "StrongP@ssw0rd123",
|
||||
"re_password": "StrongP@ssw0rd123",
|
||||
"first_name": "Ali",
|
||||
"last_name": "Veli"
|
||||
}
|
||||
```
|
||||
|
||||
### Activate Account
|
||||
```bash
|
||||
POST /api/v1/auth/users/activation/
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"uid": "MQ",
|
||||
"token": "c4h7vu-..."
|
||||
}
|
||||
```
|
||||
|
||||
### Login
|
||||
```bash
|
||||
POST /api/v1/auth/jwt/create/
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"email": "user@example.com",
|
||||
"password": "StrongP@ssw0rd123"
|
||||
}
|
||||
```
|
||||
|
||||
### Social Login
|
||||
```bash
|
||||
POST /api/v1/auth/social/google-oauth2/
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"access_token": "ya29.a0AfH6SMBx..."
|
||||
}
|
||||
```
|
||||
|
||||
Detaylı API dokümantasyonu için: [AUTH.md](./AUTH.md)
|
||||
|
||||
## 🏗️ Proje Yapısı
|
||||
|
||||
```
|
||||
server/
|
||||
├── accounts/ # Custom user app
|
||||
│ ├── migrations/
|
||||
│ ├── models.py # CustomUser model
|
||||
│ ├── serializers.py # DRF serializers
|
||||
│ ├── views.py # Social login view
|
||||
│ ├── admin.py # Admin configuration
|
||||
│ ├── pipeline.py # Social auth pipeline
|
||||
│ └── urls.py # URL routing
|
||||
├── core/ # Project settings
|
||||
│ ├── settings.py # Main settings
|
||||
│ ├── urls.py # Root URL config
|
||||
│ └── wsgi.py
|
||||
├── templates/
|
||||
│ └── email/ # Email templates
|
||||
│ ├── activation_email.html
|
||||
│ ├── activation_email.txt
|
||||
│ ├── confirmation_email.html
|
||||
│ ├── confirmation_email.txt
|
||||
│ ├── password_reset_email.html
|
||||
│ └── password_reset_email.txt
|
||||
├── manage.py
|
||||
├── req.txt # Python dependencies
|
||||
├── .env.example # Environment variables template
|
||||
├── AUTH.md # API documentation
|
||||
├── COPILOT_MEMORY.md # Development log
|
||||
└── README.md # This file
|
||||
```
|
||||
|
||||
## 🔧 Konfigürasyon
|
||||
|
||||
### Social Auth Setup
|
||||
|
||||
#### Google OAuth2
|
||||
1. [Google Cloud Console](https://console.developers.google.com/) → Create Project
|
||||
2. APIs & Services → Credentials → Create OAuth 2.0 Client ID
|
||||
3. Authorized redirect URIs: `http://localhost:8000/api/v1/social/complete/google-oauth2/`
|
||||
4. `.env` dosyasına ekleyin:
|
||||
```bash
|
||||
SOCIAL_AUTH_GOOGLE_OAUTH2_KEY=your-client-id
|
||||
SOCIAL_AUTH_GOOGLE_OAUTH2_SECRET=your-client-secret
|
||||
```
|
||||
|
||||
#### GitHub OAuth
|
||||
1. [GitHub Settings](https://github.com/settings/developers) → OAuth Apps → New OAuth App
|
||||
2. Authorization callback URL: `http://localhost:8000/api/v1/social/complete/github/`
|
||||
3. `.env` dosyasına ekleyin:
|
||||
```bash
|
||||
SOCIAL_AUTH_GITHUB_KEY=your-client-id
|
||||
SOCIAL_AUTH_GITHUB_SECRET=your-client-secret
|
||||
```
|
||||
|
||||
#### Facebook OAuth
|
||||
1. [Facebook Developers](https://developers.facebook.com/) → Create App
|
||||
2. Add Facebook Login product
|
||||
3. Valid OAuth Redirect URIs: `http://localhost:8000/api/v1/social/complete/facebook/`
|
||||
4. `.env` dosyasına ekleyin:
|
||||
```bash
|
||||
SOCIAL_AUTH_FACEBOOK_KEY=your-app-id
|
||||
SOCIAL_AUTH_FACEBOOK_SECRET=your-app-secret
|
||||
```
|
||||
|
||||
## 🧪 Testing
|
||||
|
||||
### Manuel Test
|
||||
```bash
|
||||
# Register
|
||||
curl -X POST http://localhost:8000/api/v1/auth/users/ \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"email":"test@example.com","password":"TestP@ss123","re_password":"TestP@ss123","first_name":"Test","last_name":"User"}'
|
||||
|
||||
# Check MailPit: http://localhost:8025
|
||||
|
||||
# Activate (uid ve token email'den alın)
|
||||
curl -X POST http://localhost:8000/api/v1/auth/users/activation/ \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"uid":"MQ","token":"c4h7vu-..."}'
|
||||
|
||||
# Login
|
||||
curl -X POST http://localhost:8000/api/v1/auth/jwt/create/ \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"email":"test@example.com","password":"TestP@ss123"}'
|
||||
```
|
||||
|
||||
### Unit Tests (TODO)
|
||||
```bash
|
||||
python manage.py test accounts
|
||||
```
|
||||
|
||||
## 📱 Frontend Entegrasyonu
|
||||
|
||||
### Nuxt.js / Next.js
|
||||
Detaylı entegrasyon örnekleri için [AUTH.md](./AUTH.md) dosyasına bakın.
|
||||
|
||||
**Temel Flow:**
|
||||
1. Frontend'de register form → Backend'e POST
|
||||
2. Kullanıcı email'ini kontrol eder
|
||||
3. Aktivasyon linkine tıklar → Frontend yakalayıp backend'e POST
|
||||
4. Login form → JWT tokens alınır
|
||||
5. Tokens localStorage/cookie'de saklanır
|
||||
6. Her request'te `Authorization: Bearer <token>` header'ı eklenir
|
||||
|
||||
## 🚀 Production Deployment
|
||||
|
||||
### 1. Environment Variables
|
||||
```bash
|
||||
DEBUG=False
|
||||
SECRET_KEY=<strong-random-key>
|
||||
ALLOWED_HOSTS=yourdomain.com,api.yourdomain.com
|
||||
|
||||
# PostgreSQL
|
||||
DATABASE_URL=postgresql://user:pass@host:5432/dbname
|
||||
|
||||
# SMTP Email
|
||||
EMAIL_HOST=smtp.gmail.com
|
||||
EMAIL_PORT=587
|
||||
EMAIL_USE_TLS=True
|
||||
EMAIL_HOST_USER=your-email@gmail.com
|
||||
EMAIL_HOST_PASSWORD=your-app-password
|
||||
|
||||
# Social Auth Keys
|
||||
SOCIAL_AUTH_GOOGLE_OAUTH2_KEY=...
|
||||
SOCIAL_AUTH_GITHUB_KEY=...
|
||||
```
|
||||
|
||||
### 2. Security Settings
|
||||
`settings.py` içinde production için:
|
||||
```python
|
||||
DEBUG = False
|
||||
CSRF_COOKIE_SECURE = True
|
||||
SESSION_COOKIE_SECURE = True
|
||||
SECURE_SSL_REDIRECT = True
|
||||
SECURE_HSTS_SECONDS = 31536000
|
||||
```
|
||||
|
||||
### 3. Static Files
|
||||
```bash
|
||||
python manage.py collectstatic
|
||||
```
|
||||
|
||||
### 4. Database Migration
|
||||
```bash
|
||||
python manage.py migrate
|
||||
```
|
||||
|
||||
### 5. Gunicorn/uWSGI
|
||||
```bash
|
||||
gunicorn core.wsgi:application --bind 0.0.0.0:8000
|
||||
```
|
||||
|
||||
## 📚 Dokümantasyon
|
||||
|
||||
- **API Documentation:** [AUTH.md](./AUTH.md)
|
||||
- **Cache Documentation:** [CACHE.md](./CACHE.md)
|
||||
- **Development Log:** [COPILOT_MEMORY.md](./COPILOT_MEMORY.md)
|
||||
- **Djoser Docs:** https://djoser.readthedocs.io/
|
||||
- **SimpleJWT Docs:** https://django-rest-framework-simplejwt.readthedocs.io/
|
||||
- **Python Social Auth:** https://python-social-auth.readthedocs.io/
|
||||
|
||||
## 🤝 Contributing
|
||||
|
||||
1. Fork the repository
|
||||
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
|
||||
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
|
||||
4. Push to the branch (`git push origin feature/amazing-feature`)
|
||||
5. Open a Pull Request
|
||||
|
||||
## 📝 License
|
||||
|
||||
This project is licensed under the MIT License.
|
||||
|
||||
## 👤 Author
|
||||
|
||||
Your Name - [@yourhandle](https://twitter.com/yourhandle)
|
||||
|
||||
## 🙏 Acknowledgments
|
||||
|
||||
- Django Team
|
||||
- Django REST Framework
|
||||
- Djoser
|
||||
- Python Social Auth
|
||||
- MailPit
|
||||
|
||||
---
|
||||
|
||||
**Happy Coding! 🎉**
|
||||
|
||||
Reference in New Issue
Block a user