tehran_tala/DOCKER.md

راهنمای استفاده از Docker در پروژه Gold Bank Monorepo

این پروژه به منظور استقرار (Deployment) در محیط عملیاتی و همچنین استفاده در محیط توسعه (در صورت نیاز) به صورت کامل داکرایز (Dockerized) شده است. در اینجا از معماری Turborepo به همراه مدیر بسته‌ی pnpm استفاده می‌شود، لذا استراتژی داکرایز کردن به گونه‌ای طراحی شده تا با کش (Cache) هوشمند و استفاده از turbo prune بالاترین سرعت بیلد و کمترین حجم نهایی ایمیج‌ها را به همراه داشته باشد.

معماری و ساختار ایمیج‌ها

برای هر یک از سرویس‌های پروژه یک فایل Dockerfile چند‌مرحله‌ای (Multi-stage) ایجاد شده است:

1. بک‌اند (apps/api)

• تکنولوژی: NestJS + Prisma
• مسیر: apps/api/Dockerfile
• شرح استیج‌ها:
  • Builder: با استفاده از turbo prune api --docker، کدهای مربوط به این اپلیکیشن و وابستگی‌های آن از مونو‌ریپو ایزوله می‌شود.
  • Installer: پکیج‌ها به وسیله‌ی pnpm install روی کدهای ایزوله‌شده نصب می‌گردند.
  • Build: پس از تولید Prisma Client، اپلیکیشن با دستور turbo run build کامپایل می‌گردد.
  • Runner: کدهای کامپایل‌شده (پوشه dist) در یک کانتینر سبُک node:20-alpine کپی شده و اپلیکیشن از طریق فایل dist/main.js روی پورت 3000 سرو می‌شود. کانتینر در این استیج به دلایل امنیتی با یوزر nestjs (غیر از root) اجرا می‌شود.

2. پنل ادمین (apps/admin-panel)

• تکنولوژی: Vue 3 + Vite
• مسیر: apps/admin-panel/Dockerfile
• شرح استیج‌ها: پس از طی شدن مراحل ایزوله کردن و کامپایل کد (مشابه API)، فایل‌های استاتیک نهایی به یک ایمیج nginx:alpine منتقل می‌گردند تا با پرفورمنس بالا سرو شوند (پورت 8080).

3. سمت کاربر (apps/user-app)

• تکنولوژی: Vue 3 + Vite (PWA)
• مسیر: apps/user-app/Dockerfile
• شرح استیج‌ها: دقیقاً مشابه پنل ادمین، پس از بیلد شدن، کدهای استاتیک PWA به وسیله‌ی وب‌سرور Nginx (روی پورت 8081) در دسترس قرار می‌گیرند.

پیکربندی Nginx (مسیردهی SPA)

فایل nginx-spa.conf در مسیر روت پروژه قرار دارد. وظیفه اصلی آن هدایت تمام درخواست‌هایی است که Route متناظر برای آن‌ها یافت نمی‌شود به index.html. این کار برای کارکرد صحیح Vue Router (به صورت History Mode) ضروری است. این فایل به صورت خودکار در ایمیج‌های فرانت‌اند کپی می‌شود.

---

نحوه‌ی اجرا (Docker Compose)

یک فایل docker-compose.yml در مسیر اصلی ریپازیتوری جهت هماهنگ‌سازی (Orchestration) تمام سرویس‌ها در کنار هم قرار داده شده است.

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

در روت پروژه فایلی با نام .env.example وجود دارد. قبل از اجرا، یک کپی از آن با نام .env بگیرید. متغیرهای درون این فایل شامل تنظیمات دیتابیس (مانند POSTGRES_USER و POSTGRES_PASSWORD) است که هم در دیتابیس و هم در DATABASE_URL استفاده می‌شود.

2. راه‌اندازی (Build & Up)

کافیست دستور زیر را اجرا کنید تا داکر به صورت خودکار تمام ایمیج‌ها را ساخته و کانتینرها را استارت کند:

docker-compose up --build -d

پس از اجرای موفقیت‌آمیز، سرویس‌ها به این ترتیب در دسترس خواهند بود:

• دیتابیس (PostgreSQL): localhost:5432
• رابط کاربری ادمین (Admin Panel): http://localhost:8080
• اپلیکیشن کاربران (User App): http://localhost:8081
• سرویس بک‌اند (API): http://localhost:3000

3. اجرای مایگریشن‌های دیتابیس

در صورت بالا آمدن کانتینرها برای اولین بار، دیتابیس شما خالی است. لازم است تا با استفاده از Prisma مایگریشن‌ها را روی دیتابیس اجرا کنید:

# از روی سیستم اصلی و در مسیر روت پروژه:
pnpm --filter api exec prisma migrate deploy
# یا استفاده از:
pnpm --filter api exec prisma db push

(توجه: آدرس DATABASE_URL در فایل .env باید به صورت لوکال به localhost:5432 اشاره کند تا از خارج کانتینر نیز در دسترس باشد).