frappe_docker/dokploy/MODULAR_SETUP.md

Modüler Yapı Kılavuzu

Bu doküman, Frappe ERPNext Dokploy deployment'ının modüler yapısını ve environment variable yönetimini açıklar.

🎯 Modüler Yapının Avantajları

1. Esneklik: Her environment için farklı konfigürasyon
2. Güvenlik: Hassas bilgiler .env dosyasında, Git'te değil
3. Tekrar Kullanılabilirlik: Aynı setup, farklı ayarlar
4. Versiyonlama: .env.example Git'te, gerçek .env dışında
5. Dokümantasyon: Her değişken açıklamalı
6. Bakım Kolaylığı: Merkezi konfigürasyon yönetimi

📁 Dosya Yapısı

dokploy/
├── .env.example              # Tüm değişkenler + açıklamalar + örnekler
├── .env                      # Gerçek ayarlar (Git'e commit edilmez!)
├── docker-compose.yml        # Ana deployment (environment variables kullanır)
├── docker-compose.prod.yml   # Production optimized (environment variables kullanır)
├── Dockerfile               # Image definition
├── ENV_VARIABLES.md         # Detaylı değişken dokümantasyonu
└── MODULAR_SETUP.md         # Bu dosya

🔄 Environment Variable Akışı

┌──────────────────┐
│  .env.example    │  Template (Git'te)
│  (Template)      │  - Tüm değişkenler
└────────┬─────────┘  - Varsayılan değerler
         │            - Açıklamalar
         │ Kopyala    - Örnekler
         ▼
┌──────────────────┐
│      .env        │  Gerçek Konfigürasyon (Git'te DEĞİL!)
│  (Actual Config) │  - Özelleştirilmiş değerler
└────────┬─────────┘  - Production şifreleri
         │            - Gerçek domain'ler
         │ Okunur
         ▼
┌──────────────────┐
│ docker-compose   │  Deployment
│     .yml         │  - ${VARIABLE:-default} formatı
└────────┬─────────┘  - Fallback değerler
         │            - Tüm servisler
         │ Deploy
         ▼
┌──────────────────┐
│   Containers     │  Çalışan Sistem
│    (Running)     │  - Konfigüre edilmiş
└──────────────────┘  - Production ready

🛠️ Kurulum Adımları

1. Template'i Kopyalama

# Dokploy klasörüne gidin
cd dokploy

# .env.example'ı .env olarak kopyalayın
cp .env.example .env

2. Konfigürasyon Düzenleme

# .env dosyasını açın
nano .env

# Veya
vim .env

# Veya favorite editörünüz
code .env

3. Zorunlu Değerleri Güncelleme

Minimum olarak şunları değiştirin:

# Site bilgisi
SITE_NAME=erp.yourdomain.com

# Güçlü şifreler (ÖNEMLİ!)
ADMIN_PASSWORD=YourSecurePassword123!
DB_PASSWORD=YourDatabasePassword456!

4. İsteğe Bağlı Optimizasyonlar

İhtiyaca göre şunları da ayarlayın:

# Performance
PROXY_READ_TIMEOUT=300
CLIENT_MAX_BODY_SIZE=100m

# Deployment stratejisi
PULL_POLICY=always
RESTART_POLICY=unless-stopped

# Versions
MARIADB_VERSION=10.6
REDIS_VERSION=7

5. Deployment

# Docker Compose ile deploy
docker-compose up -d

# Veya production config ile
docker-compose -f docker-compose.prod.yml up -d

📊 Environment Variable Kategorileri

1. Zorunlu Değişkenler

SITE_NAME=           # Site domain
ADMIN_PASSWORD=      # Admin şifresi
DB_PASSWORD=         # DB şifresi

2. Network & Port

HTTP_PORT=80
UPSTREAM_REAL_IP_ADDRESS=127.0.0.1
UPSTREAM_REAL_IP_HEADER=X-Forwarded-For

3. Frappe Framework

FRAPPE_SITE_NAME_HEADER=$$host
FRAPPE_BRANCH=version-15

4. Nginx

PROXY_READ_TIMEOUT=120
CLIENT_MAX_BODY_SIZE=50m

5. Docker

CUSTOM_IMAGE=erpnext-complete
CUSTOM_TAG=latest
PULL_POLICY=build
RESTART_POLICY=unless-stopped

6. Database

DB_HOST=mariadb
DB_PORT=3306
MARIADB_VERSION=10.6

7. Redis

REDIS_CACHE=redis-cache:6379
REDIS_QUEUE=redis-queue:6379
REDIS_VERSION=7

🔐 Güvenlik Best Practices

.env Dosyası Yönetimi

1. Asla Git'e Commit Etmeyin

   # .gitignore kontrol
   cat .gitignore | grep .env
   
   # Output: .env (olmalı!)
   

2. Güvenli Depolama

   • Password manager kullanın
   • Encrypted backup alın
   • Team'le güvenli paylaşın (1Password, LastPass vb.)

3. Şifre Güvenliği

   # Güçlü şifre oluşturma
   openssl rand -base64 32
   
   # Veya
   pwgen -s 20 1
   

Environment Separation

Development (.env.dev)

SITE_NAME=dev.localhost
ADMIN_PASSWORD=DevPassword123
PULL_POLICY=build
DEVELOPER_MODE=1

Staging (.env.staging)

SITE_NAME=staging.yourdomain.com
ADMIN_PASSWORD=StagingSecure456!
PULL_POLICY=always
CUSTOM_TAG=develop

Production (.env.prod)

SITE_NAME=erp.yourdomain.com
ADMIN_PASSWORD=ProdVerySecure789!
PULL_POLICY=always
CUSTOM_TAG=v1.0.0
RESTART_POLICY=unless-stopped

🔄 Değişken Güncellemeleri

Değişiklik Yapma

# 1. .env dosyasını düzenleyin
nano .env

# 2. Değişiklikleri uygulayın
docker-compose down
docker-compose up -d

# Veya sadece yeniden başlatma
docker-compose restart

Runtime'da Değişiklik

Bazı değişiklikler container yeniden oluşturma gerektirir:

# Image değişikliği
docker-compose up -d --build

# Volume değişikliği  
docker-compose down -v
docker-compose up -d

# Tüm yeniden oluşturma
docker-compose up -d --force-recreate

📝 Dokümantasyon

Değişken Ekleme

Yeni bir environment variable eklerken:

1. .env.example'a ekleyin

   # Yeni Özellik
   # Açıklama: Ne işe yarar
   # Varsayılan: default_value
   # Örnek: example_value
   NEW_VARIABLE=default_value
   

2. docker-compose.yml'e ekleyin

   environment:
     NEW_VARIABLE: ${NEW_VARIABLE:-default_value}
   

3. ENV_VARIABLES.md'yi güncelleyin

   • Detaylı açıklama
   • Kullanım örnekleri
   • Best practices

4. CHANGELOG.md'ye not düşün

   • Yeni özellik olarak işaretleyin
   • Migration notları ekleyin

🎯 Kullanım Senaryoları

Senaryo 1: Multi-Environment Setup

# Development
cp .env.example .env.dev
nano .env.dev
docker-compose --env-file .env.dev up -d

# Production
cp .env.example .env.prod
nano .env.prod
docker-compose --env-file .env.prod -f docker-compose.prod.yml up -d

Senaryo 2: Team Collaboration

# Her developer kendi .env'ini oluşturur
cp .env.example .env.local
nano .env.local

# Ortak ayarlar .env.example'da
git add .env.example
git commit -m "Update environment template"

Senaryo 3: CI/CD Integration

# .github/workflows/deploy.yml
- name: Create .env
  run: |
    echo "SITE_NAME=${{ secrets.SITE_NAME }}" >> .env
    echo "ADMIN_PASSWORD=${{ secrets.ADMIN_PASSWORD }}" >> .env
    echo "DB_PASSWORD=${{ secrets.DB_PASSWORD }}" >> .env
        
- name: Deploy
  run: docker-compose up -d

Senaryo 4: Dokploy Deployment

Dokploy UI'da environment variables:

• .env.example dosyasından kopyalayın
• Her değeri Dokploy'a yapıştırın
• Secret olanları "Secret" olarak işaretleyin

🔍 Troubleshooting

Variable Tanınmıyor

# .env dosyası var mı?
ls -la .env

# Doğru formatta mı?
cat .env | grep SITE_NAME

# Docker Compose'a belirtin
docker-compose --env-file .env config

Değişiklikler Uygulanmıyor

# Container'ları yeniden oluşturun
docker-compose up -d --force-recreate

# Image'i yeniden build edin
docker-compose build --no-cache

# Volume'ları temizleyin (DİKKAT: Veri kaybı!)
docker-compose down -v

Özel Karakter Sorunları

# Tırnak kullanın
ADMIN_PASSWORD="MyPass@123!"

# Veya escape edin
ADMIN_PASSWORD=MyPass\@123\!

📚 İlgili Dokümantasyon

• .env.example - Tüm değişkenler ve örnekler
• ENV_VARIABLES.md - Detaylı değişken açıklamaları
• DEPLOYMENT.md - Deployment kılavuzu
• QUICKSTART.md - Hızlı başlangıç
• docker-compose.yml - Servis tanımları

🎓 Best Practices Özeti

✅ DO (YAPIN)

• .env.example kullanın template olarak
• Güçlü şifreler kullanın
• Her environment için ayrı .env
• Hassas bilgileri şifreleyin
• Dokümantasyonu güncel tutun
• Versiyonları pin'leyin (production)

❌ DON'T (YAPMAYIN)

• .env'i Git'e commit etmeyin
• Weak passwords kullanmayın
• Production'da default değerler bırakmayın
• .env dosyasını paylaşmayın (şifresiz)
• Dokümantasyonu skip etmeyin
• Test etmeden deploy etmeyin

---

Son Güncelleme: 2025-10-13
Versiyon: 1.0.0