Backend-Api/DOCKER_ENVIRONMENT_GUIDE.md

🐳 راهنمای استفاده از Docker برای Gozareshgir

چرا ASPNETCORE_ENVIRONMENT=Production در Docker؟

❌ اشتباه رایج:

# docker-compose.yml
ASPNETCORE_ENVIRONMENT=Development  # ❌ اشتباه

✅ روش صحیح:

# ServiceHost/.env
ASPNETCORE_ENVIRONMENT=Production  # ✅ صحیح

دلایل:

1. Docker باید شبیه سرور باشه - محیط Docker باید دقیقاً مثل Production رفتار کنه
2. Static Web Assets نیاز نیست - در Production فقط فایل‌های compiled نیاز هستن
3. بهینه‌سازی Performance - حالت Production بهینه‌تر و سریع‌تره
4. امنیت بیشتر - خطاهای جزئی نمایش داده نمی‌شن
5. تست واقعی - اگر در Docker مشکلی نباشه، در Production هم مشکلی نخواهد بود

---

📋 مراحل راه‌اندازی

1️⃣ تنظیم فایل .env

# کپی کردن فایل نمونه
cp ServiceHost/.env.example ServiceHost/.env

# ویرایش و تنظیم متغیرها
notepad ServiceHost/.env

مهم‌ترین تنظیمات:

# ✅ همیشه Production
ASPNETCORE_ENVIRONMENT=Production

# پورت‌ها
HTTP_PORT=5003
HTTPS_PORT=5004

# اتصال به دیتابیس روی Host
ConnectionStrings__MesbahDb=Server=host.docker.internal;Database=mesbah_db;...
MongoDb__ConnectionString=mongodb://host.docker.internal:27017

2️⃣ تولید Certificate برای HTTPS

# اجرای اسکریپت تولید certificate
.\scripts\generate-cert.ps1

یا دستی:

# ساخت پوشه certs
mkdir ServiceHost\certs

# تولید certificate
dotnet dev-certs https -ep ServiceHost\certs\aspnetcore.pfx -p Dev123456 --trust

3️⃣ Build و اجرای Docker

# Build
docker-compose build

# اجرا
docker-compose up -d

# مشاهده logs
docker-compose logs -f servicehost

---

🔍 بررسی وضعیت

چک کردن Environment:

# وارد شدن به container
docker exec -it gozareshgir-servicehost bash

# چک کردن متغیر محیط
echo $ASPNETCORE_ENVIRONMENT
# باید نمایش دهد: Production

دسترسی به برنامه:

• HTTPS: https://localhost:5004
• HTTP: http://localhost:5003
• Health Check: https://localhost:5004/health

مشاهده Logs:

# مشاهده لاگ‌های زنده
docker-compose logs -f servicehost

# مشاهده 100 خط آخر
docker-compose logs --tail=100 servicehost

# مشاهده لاگ‌های فایل داخل container
docker exec -it gozareshgir-servicehost cat /app/Logs/gozareshgir_log.txt

لاگ‌ها در دو جا ذخیره می‌شوند:

1. ✅ Console - برای docker-compose logs
2. ✅ File - در /app/Logs/gozareshgir_log.txt

---

🆚 تفاوت Development vs Production

Development (Visual Studio/Rider):

// launchSettings.json
{
  "ASPNETCORE_ENVIRONMENT": "Development"  // ✅ در IDE
}

ویژگی‌ها:

• Static Web Assets فعال
• Hot Reload
• نمایش خطاهای جزئی
• Database Browser Page
• Debugging

Production (Docker):

# .env
ASPNETCORE_ENVIRONMENT=Production  # ✅ در Docker

ویژگی‌ها:

• فایل‌های compiled و بهینه
• بدون Static Web Assets
• خطاهای Generic
• Performance بهتر
• مثل سرور واقعی

---

🐛 رفع مشکلات رایج

❌ خطا: DirectoryNotFoundException: /home/app/.nuget/packages/...

دلیل: Static Web Assets در Production نیاز نیست

راه‌حل: این مشکل با کد زیر در Program.cs حل شده:

Environment.SetEnvironmentVariable("ASPNETCORE_HOSTINGSTARTUPASSEMBLIES", "");

❌ خطا: Certificate Error

# تولید مجدد certificate
dotnet dev-certs https --clean
dotnet dev-certs https -ep ServiceHost\certs\aspnetcore.pfx -p Dev123456 --trust

❌ نمی‌تونه به SQL Server/MongoDB وصل بشه

بررسی کنید:

• SQL Server و MongoDB روی host machine در حال اجرا هستن
• host.docker.internal در connection string استفاده شده
• پورت‌ها باز هستن

---

📁 ساختار فایل‌های تنظیمات

OriginalGozareshgir/
├── docker-compose.yml           # ✅ ساده - فقط reference به .env
├── ServiceHost/
│   ├── .env                     # ✅ تمام متغیرها اینجا
│   ├── .env.example            # 📝 نمونه برای Git
│   ├── Dockerfile
│   ├── certs/
│   │   └── aspnetcore.pfx      # HTTPS Certificate
│   └── Program.cs              # ✅ Static Web Assets غیرفعال

---

🚀 Production Deployment

برای deploy روی سرور واقعی:

1. تغییر .env:

ASPNETCORE_ENVIRONMENT=Production
Domain=.yourdomain.com
ConnectionStrings__MesbahDb=Server=your-db-server;...
HTTPS_PORT=443
HTTP_PORT=80

2. Certificate واقعی:

# استفاده از Let's Encrypt یا Certificate معتبر
ASPNETCORE_Kestrel__Certificates__Default__Path=/app/certs/yourdomain.pfx
ASPNETCORE_Kestrel__Certificates__Default__Password=SecurePassword

3. Deploy:

docker-compose up -d --build

---

📚 منابع

• ASP.NET Core Environments
• Docker for .NET
• HTTPS in Docker

---

✅ Checklist

• فایل .env از .env.example کپی شده
• متغیر ASPNETCORE_ENVIRONMENT=Production تنظیم شده
• Certificate HTTPS تولید شده
• SQL Server و MongoDB روی host در حال اجرا هستن
• docker-compose build بدون خطا اجرا شده
• برنامه از طریق https://localhost:5004 قابل دسترسی است