# دیپلوی ClinicPro روی Coolify (Docker Compose)

این راهنما نحوهٔ دیپلوی بک‌اند ClinicPro (Symfony 7.4 + پنل React) را روی **Coolify** با Build Pack از نوع **Docker Compose** توضیح می‌دهد.

> همهٔ فایل‌های دیپلوی در ریشهٔ ریپو هستند: `Dockerfile`، `docker-compose.yml`، پوشهٔ `docker/` و `.env.coolify.example`.
> فایل‌های `compose.yaml`، `compose.override.yaml` و `.ddev/` مخصوص محیط لوکال (ddev) هستند و **در دیپلوی نقشی ندارند**.

---

## معماری دیپلوی

`docker-compose.yml` پنج سرویس بالا می‌آورد:

| سرویس | نقش | نکته |
|-------|-----|------|
| `app` | وب (PHP-FPM + Nginx) | دامنه به این سرویس اختصاص می‌یابد (پورت ۸۰). `RUN_INIT=1` → migration و تولید کلید JWT |
| `worker-async` | مصرف صف `async` (ارسال SMS، مصرف‌کنندهٔ رویدادهای دامنه) | `RUN_INIT=0` |
| `worker-scheduler` | مصرف `scheduler_default` (انقضای نوبت‌ها، انتشار صندوق خروجی رویدادها، هر دقیقه) | `RUN_INIT=0` |
| `mariadb` | دیتابیس MariaDB 11.8 | healthcheck دارد؛ سرویس‌های اپ منتظر سالم‌شدن آن می‌مانند |
| `redis` | Messenger transport + کش/OTP | با appendonly persist می‌شود |

هر سه سرویس اپ از یک image یکسان (همان `Dockerfile`) ساخته می‌شوند و فقط `command`/`RUN_INIT` آن‌ها متفاوت است.

---

## مراحل دیپلوی

### ۱. ساخت Resource در Coolify

1. **New Resource → Public/Private Repository** و ریپوی `clinicpro` را انتخاب کن.
2. **Build Pack** را روی **Docker Compose** بگذار (نه Nixpacks).
3. در تنظیمات:
   - **Branch:** `main`
   - **Base Directory:** `/` (ریشهٔ ریپو)
   - **Docker Compose File:** `docker-compose.yml`

### ۲. اختصاص دامنه

- در سرویس `app`، **همهٔ** دامنه‌هایی که باید سرویس بگیرند را وارد کن — هم دامنهٔ API بک‌اند و هم همهٔ دامنه‌های فرانت‌اند (`nobat724.com` و همهٔ `*-nobat.ir`). Coolify لیست دامنهٔ کامادار را روی یک سرویس می‌پذیرد.
- چون کانتینر روی پورت `80` گوش می‌دهد، نیازی به افزودن پورت به دامنه نیست.
- Coolify به‌صورت خودکار برای هر دامنه TLS را از طریق Traefik (Let's Encrypt) صادر می‌کند.

> دو مفهوم را اشتباه نگیر:
> - **اختصاص دامنه در UI** = Traefik برای آن دامنه روت و گواهی TLS می‌سازد.
> - **`CORS_ALLOW_ORIGIN` / `ALLOWED_FRONTEND_HOSTS`** = سیمفونی به آن origin اجازهٔ مرورگری/پرداخت می‌دهد.
>
> یک دامنهٔ جدید معمولاً به **هر دو** نیاز دارد: هم در UI کولیفای اضافه شود، هم در `docker/frontend-domains.json` (و سپس بازتولید env). به بخش «چند دامنه فرانت‌اند» پایین مراجعه کن.

### ۳. متغیرهای محیطی

محتوای [`.env.coolify.example`](../../.env.coolify.example) را در تب **Environment Variables** وارد کن. الزامی‌ها پیش از اولین دیپلوی:

| متغیر | توضیح |
|-------|-------|
| `APP_SECRET` | `php -r "echo bin2hex(random_bytes(32));"` |
| `JWT_PASSPHRASE` | `openssl rand -hex 32` — **باید قبل از اولین استارت موجود باشد** (کلید JWT با آن ساخته می‌شود) |
| `DB_PASSWORD` | پسورد یوزر دیتابیس |
| `DB_ROOT_PASSWORD` | پسورد root مریادی‌بی |
| `APP_BASE_URL` | دامنهٔ **خودِ بک‌اند** (مثلاً `https://api.nobat724.com`) — برای callback پرداخت و URL مطلق |
| `ALLOWED_FRONTEND_HOSTS` / `CORS_ALLOW_ORIGIN` | دامنه‌های **فرانت‌اند** (چندتایی) — به بخش «چند دامنه» پایین مراجعه کن |
| `TRUSTED_PROXIES` | پیش‌فرض رنج شبکهٔ داخلی داکر (در فایل نمونه هست) |
| `API_IR_TOKEN` | توکن استعلام هویت (خالی = استعلام رد می‌شود) |

> `DATABASE_URL`، `MESSENGER_TRANSPORT_DSN` و `REDIS_URL` در خودِ compose از نام سرویس‌ها (`mariadb`/`redis`) ساخته می‌شوند؛ در UI تعریف نکن.
> کلیدهای **SMS** و **درگاه پرداخت** از DB («تنظیمات سایت») خوانده می‌شوند، نه از env.
> می‌توانی به‌جای hardcode از magic variableهای Coolify استفاده کنی، مثلاً `DB_PASSWORD=${SERVICE_PASSWORD_DB}`.

#### چند دامنه فرانت‌اند (مهم)

این بک‌اند به ده‌ها دامنهٔ شهری سرویس می‌دهد (`nobat724.com` و `*-nobat.ir`). دو متغیر باید همهٔ این دامنه‌ها را پوشش دهند:

- **`ALLOWED_FRONTEND_HOSTS`** — لیست host با کاما؛ در validate کردن host بازگشتِ پرداخت استفاده می‌شود (تطبیق دقیق در `PaymentController::isAllowedFrontend`).
- **`CORS_ALLOW_ORIGIN`** — یک regex واحد (nelmio با `origin_regex: true`) که فقط `https` و دقیقاً همان host‌ها را می‌پذیرد.

هر دو مقدار به‌صورت **خودکار** از فایل [`docker/frontend-domains.json`](../../docker/frontend-domains.json) تولید می‌شوند. برای افزودن یا حذف یک دامنه:

```bash
# ۱) یک رکورد به آرایهٔ "domains" در docker/frontend-domains.json اضافه/حذف کن، مثلاً:
#    { "domain": "newcity-nobat.ir", "label": "شهر جدید" }
# ۲) مقادیر جدید را تولید کن:
ddev exec php docker/gen-cors-env.php       # لوکال
#   یا روی سرور داخل کانتینر app:
php docker/gen-cors-env.php
# ۳) خروجی (CORS_ALLOW_ORIGIN و ALLOWED_FRONTEND_HOSTS) را در Coolify جایگزین کن و دوباره deploy کن
```

> فیلد `label` فقط برای خوانایی است و در تولید env استفاده نمی‌شود؛ فقط `domain` مهم است.

> `payment_allowed_frontend_hosts` در «تنظیمات سایت» (DB) بر مقدار env اولویت دارد؛ اگر آن را در DB ست کرده‌ای، آن مرجع است.

### ۴. Persistent Storage (حیاتی)

این volumeها در compose تعریف شده‌اند و Coolify آن‌ها را persist می‌کند:

| Volume | مسیر | چرا مهم است |
|--------|------|-------------|
| `jwt_keys` | `/app/config/jwt` | **مهم‌ترین.** کلید JWT بین دیپلوی‌ها باید ثابت بماند؛ در غیر این صورت هر دیپلوی همهٔ توکن‌ها را باطل و همهٔ کاربران را logout می‌کند |
| `uploads_public` | `/app/public/uploads` | فایل‌های آپلودی عمومی |
| `uploads_var` | `/app/var/uploads` | فایل‌های آپلودی خصوصی |
| `mariadb_data` | `/var/lib/mysql` | دادهٔ دیتابیس |
| `redis_data` | `/data` | پایداری Redis |

> مطمئن شو در Coolify این volumeها به‌صورت **named volume** (نه ephemeral) باقی می‌مانند.

### ۵. اولین دیپلوی و ساخت ادمین

1. **Deploy** را بزن. سرویس `app` هنگام استارت به‌صورت خودکار:
   - کلید JWT می‌سازد (اگر روی volume نباشد)،
   - کش prod را warm می‌کند،
   - migrationها را با `--all-or-nothing` اجرا می‌کند.
2. بعد از سالم‌شدن سرویس‌ها، از **Terminal** سرویس `app` در Coolify، ادمین اولیه را بساز:
   ```bash
   php bin/console app:create-admin
   ```

---

## نکات عملیاتی

- **Worker‌ها:** اگر `worker-scheduler` بالا نباشد، نوبت‌های رزرو ولی پرداخت‌نشده **آزاد نمی‌شوند**. اگر `worker-async` بالا نباشد، **SMS ارسال نمی‌شود**. هر دو در همین compose مدیریت می‌شوند و با `restart: unless-stopped` خودکار بازمی‌گردند.
- **Migration در دیپلوی‌های بعدی:** فقط سرویس `app` (با `RUN_INIT=1`) migration اجرا می‌کند تا بین سرویس‌ها race رخ ندهد. هر دیپلوی، migrationهای جدید را اعمال می‌کند.
- **Health check:** سرویس `app` با یک fsockopen روی پورت 80 سالم‌بودن خود را گزارش می‌دهد.
- **Trusted Proxies:** مقدار `TRUSTED_PROXIES` به Symfony می‌گوید به هدرهای `X-Forwarded-*` از Traefik اعتماد کند تا `https` و IP واقعی کلاینت درست تشخیص داده شوند. در محیط لوکال (ddev) این متغیر تنظیم نمی‌شود و مقدار پیش‌فرض خالی است.
- **بدون شبکهٔ سفارشی:** طبق توصیهٔ Coolify، در compose هیچ `networks:` سفارشی تعریف نشده تا روتینگ Traefik پایدار بماند.

---

## رفع اشکال

| نشانه | علت محتمل | راه‌حل |
|-------|-----------|--------|
| همهٔ کاربران بعد از دیپلوی logout می‌شوند | volume `jwt_keys` persist نشده | بررسی named volume بودن آن |
| خطای اتصال به دیتابیس هنگام استارت | `app` قبل از سالم‌شدن `mariadb` بالا آمده | `depends_on: condition: service_healthy` این را پوشش می‌دهد؛ صبر کن یا لاگ `mariadb` را ببین |
| پنل admin سفید/بدون استایل | دارایی‌های `public/build` ساخته نشده | بررسی موفقیت stage `assets` در لاگ build (`yarn build`) |
| تولید کلید JWT شکست می‌خورد | `JWT_PASSPHRASE` تنظیم نشده | متغیر را در Coolify ست کن و دوباره deploy کن |
| تصاویر/فایل‌های آپلودی بعد از ری‌دیپلوی ناپدید می‌شوند | volumeهای uploads persist نشده | بررسی `uploads_public` / `uploads_var` |
