clinicpro/.claude/prompt/coolify-docker-production-hardening.md

# سخت‌سازی و بازبینی Production استک Docker برای Coolify (MariaDB/Redis مستقل)

## پروژه

`clinicpro` (backend / deploy / infra)

## ⚠️ قانون شماره ۱ — اول مستندات، بعد کد

قبل از هرگونه تغییر در فایل‌های Docker، **مستندات رسمی Coolify را با WebFetch بخوان** و هر تصمیم را بر پایه‌ی آن‌ها بگیر، نه دانش قبلی. دستِ‌کم این صفحات:

- https://coolify.io/docs/get-started/introduction
- https://coolify.io/docs/applications/build-packs/docker-compose
- https://coolify.io/docs/knowledge-base/docker/compose
- https://coolify.io/docs/databases/mariadb
- https://coolify.io/docs/databases/redis

موضوعاتی که باید از داک تأیید شوند (نه از حافظه): Docker Compose Build Pack، **Connect to Predefined Network**، Environment Variables، Healthcheck، Persistent Storage (Volumes)، Reverse Proxy/Traefik، Domains، Resource Limits، Raw Docker Compose.

اگر دانش قبلی با داک تناقض داشت → **داک ملاک است**. هر بخش که در داک پیدا نشد، در گزارش ذکر کن که «در داک نبود، بر اساس best practice تصمیم گرفته شد».

## زمینه

استک دیپلوی این پروژه قبلاً ساخته و چند بار روی Coolify دیپلوی شده و چند باگ رفع شده (node20→22، FPM clear_env، preload perms، باگ‌های migration روی DB خالی، codeload flaky، نبود `symfony/redis-messenger`، اتصال به DB/Redis مستقل، healthcheck). این تسک یک **بازبینی کامل و سخت‌سازی** استکِ موجود است تا کاملاً با مستندات Coolify هم‌خوان شود و در دیپلوی خطا ندهد — **نه ساخت از صفر**. فایل‌های فعلی را بهبود بده، دوباره‌سازی نکن.

معماری تثبیت‌شده: **MariaDB و Redis، Database Resourceهای مستقل Coolify هستند** (نه داخل compose). اپ از طریق شبکه‌ی predefined (`coolify`) و hostname `mariadb-<uuid>`/`redis-<uuid>` وصل می‌شود. هیچ `localhost` و هیچ hardcode.

## وضعیت فعلی پروژه (واقعی — بررسی شده)

| واقعیت | مقدار |
|---|---|
| PHP | `>=8.2` (image: `php:8.2-fpm-alpine`) |
| Symfony | `7.4.*` |
| اکستنشن‌های نصب‌شده | `pdo_mysql`, `intl`, `opcache`, `redis` (phpredis 6.1.0 از سورس GitHub) |
| اکستنشن‌های لازمِ composer | فقط `ext-ctype`, `ext-iconv` (هر دو bundled) |
| Symfony cache adapter | `cache.adapter.redis` با `%env(REDIS_URL)%` (config/packages/cache.yaml) |
| Session | `session.storage.factory.mock_file` (فایلی، نه redis) |
| Messenger transports | `async` (redis، نیاز `symfony/redis-messenger` ✔ نصب شد)، `scheduler_default`، `failed` (doctrine) |
| سرویس‌ها | `app` (RUN_INIT=1) + `worker-async` + `worker-scheduler`؛ image مشترک `clinicpro-app:latest` |
| شبکه | `networks: [coolify]` external روی هر ۳ سرویس |
| Healthcheck فعلی | app: `php get_headers /health`؛ workerها: `ps | grep messenger:consume` |
| کاربر اجرا | **root** (supervisord `user=root`, بدون `USER` در Dockerfile) ⚠️ |
| APCu | **نصب نیست** (cache از redis است؛ APCu فقط برای کش لوکال opcache/symfony مفید) |
| Graceful shutdown | supervisord PID 1، بدون `STOPSIGNAL`/`stopwaitsecs` تنظیم‌شده ⚠️ |

## فایل‌های مرتبط

| فایل | نقش |
|------|-----|
| `clinicpro/Dockerfile` | multi-stage (vendor→assets→runtime)؛ نصب اکستنشن، perms، entrypoint |
| `clinicpro/docker-compose.yml` | استک Coolify (app + 2 worker)، networks، healthcheck |
| `clinicpro/.dockerignore` | استثناها |
| `clinicpro/docker/entrypoint.sh` | wait-for-DB، JWT keygen، cache، migrate (فقط RUN_INIT=1) |
| `clinicpro/docker/supervisord.conf` | php-fpm + nginx |
| `clinicpro/docker/php/php.ini` | opcache + perf |
| `clinicpro/docker/php/zz-pool.conf` | FPM pool: `clear_env = no` |
| `clinicpro/docker/nginx/default.conf` | nginx |
| `clinicpro/src/Shared/Controller/HealthController.php` | route `/health` |
| `clinicpro/docs/DEPLOY.md` | راهنمای دیپلوی |
| `clinicpro/.env.coolify.example` | نمونه env |

## وظایف

> هر وظیفه: اول داکِ مرتبط را بخوان، بعد اعمال کن، بعد با `docker buildx build --platform linux/amd64` تست کن. هیچ مقدار hardcode، فقط `${VAR}`. هیچ custom network جز `coolify` external.

### ۱. اجرای غیر-root (Security Hardening)

الان کانتینر root اجرا می‌شود. باید non-root شود **بدون شکستن** preload (که الان `opcache.preload_user = www-data` است) و nginx/fpm.

- در `supervisord.conf`، php-fpm pool از قبل به‌صورت www-data اجرا می‌شود؛ ولی master supervisord و nginx master root هستند. بررسی کن آیا می‌توان کل استک را با `USER www-data` اجرا کرد یا nginx master نیاز root دارد (برای bind پورت ۸۰).
- اگر nginx به پورت ۸۰ نیاز root دارد: یا nginx را روی پورت **8080 (non-privileged)** ببر و در compose/healthcheck و Coolify port را ۸۰۸۰ کن (Traefik به هر پورتی روت می‌کند)، سپس `USER www-data` در Dockerfile + `user=www-data` در supervisord.
- مطمئن شو `var/cache`, `var/log`, `var/uploads`, `public/uploads`, `config/jwt` برای www-data نوشتنی‌اند (chown موجود است؛ تکمیلش کن).
- داک Coolify درباره‌ی port/Traefik را بخوان تا مطمئن شوی تغییر پورت به ۸۰۸۰ مشکلی ایجاد نمی‌کند.

> اگر non-root باعث ریسک شکستن شد و در زمان محدود قابل‌اطمینان نبود، حداقل nginx/fpm worker‌ها را non-root نگه دار (الان هستند) و در گزارش توضیح بده چرا master root ماند.

### ۲. healthcheck.sh مستقل + بازبینی healthcheckها

پرامپت یک `docker/healthcheck.sh` می‌خواهد. به‌جای دستور inline طولانی در compose:

- یک `docker/healthcheck.sh` بساز که `/health` را چک کند (با `php -r` get_headers یا اگر در image موجود است `curl -fsS`؛ از روی Dockerfile مطمئن شو کدام در runtime هست — `curl` در build استفاده شده ولی شاید در runtime نمانده باشد، چک کن).
- در Dockerfile کپی + executable کن، در `docker-compose.yml` healthcheck سرویس `app` را به `["CMD","/usr/local/bin/healthcheck.sh"]` تغییر بده.
- healthcheckهای worker (ps grep) را نگه دار یا به اسکریپت منتقل کن.
- مقادیر `interval/timeout/retries/start_period` را با توصیه‌ی داک Coolify (اگر دارد) هم‌سو کن.

### ۳. opcache.ini جدا + بازبینی perf‌ها

پرامپت `opcache.ini` جدا می‌خواهد. الان opcache داخل `php.ini` است.

- بخش opcache را از `php.ini` به یک `docker/php/opcache.ini` منتقل کن و در Dockerfile جداگانه کپی کن (`/usr/local/etc/php/conf.d/`). تنظیمات فعلی opcache دست‌نخورده بماند (preload, validate_timestamps=0, ...).
- بررسی کن `realpath_cache`, `memory_limit`, `upload_max_filesize`/`post_max_size` (الان 16M) با `MAX_FILE_SIZE_BYTES=5242880` (۵MB در env) هم‌خوان است — اگر آپلود تا ۵MB است، 16M کافی است، نگه دار.

### ۴. APCu — تصمیم مستند

- چون Symfony cache از **redis** است نه apcu، نصب APCu **اجباری نیست**. ولی اگر می‌خواهی کش متادیتای Doctrine/annotation روی apcu لوکال باشد (سریع‌تر از redis برای read-heavy)، APCu را با همان روش source (یا `docker-php-ext-...`/pecl-free) اضافه کن.
- تصمیم را در گزارش مستند کن: یا «APCu لازم نیست چون cache=redis» یا «اضافه شد برای X». hardcode نکن؛ اگر اضافه شد، در runtime enable شود.

### ۵. Graceful shutdown / signal handling

- supervisord را برای shutdown تمیز تنظیم کن: `stopsignal`, `stopwaitsecs` برای php-fpm/nginx، و مطمئن شو سیگنال SIGTERM از داکر به فرزندها می‌رسد.
- workerها (`messenger:consume`) به SIGTERM پاسخ می‌دهند (Symfony Messenger خودش graceful است با `--time-limit`)؛ مطمئن شو داکر مستقیم پروسه‌ی consume را اجرا می‌کند (الان `command: php bin/console messenger:consume ...` مستقیم است ✔) و `stop_grace_period` در compose برای workerها کافی است (پیش‌فرض 10s؛ شاید 30s بهتر باشد تا پیام در حال پردازش تمام شود).

### ۶. Resource limits (طبق داک Coolify)

- داک Coolify درباره‌ی Resource Limits را بخوان. اگر در compose پشتیبانی می‌شود (`deploy.resources.limits` در سطح Coolify یا UI)، توصیه‌ی mem/cpu برای `app` و workerها را در `docs/DEPLOY.md` مستند کن. اگر Coolify limits را از UI می‌گیرد نه compose، فقط در داک ذکر کن.

### ۷. بازبینی نهایی هم‌خوانی با Coolify + به‌روزرسانی DEPLOY.md

- مطمئن شو هیچ `localhost`/`127.0.0.1` برای DB/Redis نیست (همه از `${DATABASE_URL}`/`${REDIS_URL}`/`${MESSENGER_TRANSPORT_DSN}`).
- مطمئن شو فقط شبکه‌ی `coolify` external است و هر ۳ سرویس به آن وصل‌اند.
- `docs/DEPLOY.md` را با هر تغییر (پورت non-root، healthcheck.sh، resource limits) به‌روز کن.
- چک‌لیست نهایی را در انتهای گزارش بده (پایین).

## تست (اجباری — بعد از تغییرات)

روی **linux/amd64** (معماری Coolify):

```bash
# build کامل
docker buildx build --platform linux/amd64 --target runtime --load -t clinicpro-test -f Dockerfile .

# اکستنشن‌ها لود؟
docker run --rm --platform linux/amd64 --entrypoint php clinicpro-test -m | grep -iE 'pdo_mysql|intl|redis|opcache|apcu'

# non-root؟
docker run --rm --platform linux/amd64 --entrypoint id clinicpro-test

# boot prod بدون خطا (با env ساختگی)
docker run --rm --platform linux/amd64 -e APP_ENV=prod -e APP_DEBUG=0 -e APP_SECRET=x \
  -e DATABASE_URL="mysql://u:p@127.0.0.1:3306/d?serverVersion=mariadb-11.8.0" \
  -e JWT_PASSPHRASE=x -e CORS_ALLOW_ORIGIN='^x$' -e APP_BASE_URL=http://x \
  -e ALLOWED_FRONTEND_HOSTS=x -e TRUSTED_PROXIES=10.0.0.0/8 -e API_IR_BASE_URL=x -e API_IR_TOKEN= \
  -e MESSENGER_TRANSPORT_DSN=redis://127.0.0.1:6379/m -e REDIS_URL=redis://127.0.0.1:6379 \
  --entrypoint php clinicpro-test bin/console about | grep -iE 'environment|debug'

# اتصال واقعی DB+Redis مستقل + migration + /health (مثل سشن‌های قبل: کانتینر mariadb+redis روی یک docker network بساز،
# سپس app را با DATABASE_URL/REDIS_URL به آن‌ها وصل کن، RUN_INIT=1، و /health را curl کن)

# اعتبار YAML
docker compose config   # با env ساختگی
```

موارد ۱..۱۴ پرامپت اصلی (healthcheck، logها، اتصال DB/Redis، cache، migration، response، perms، restart، graceful shutdown، production mode) را با همین روش پوشش بده. هر مشکل را همان‌جا رفع کن.

## نکات مهم

- **هیچ MariaDB/Redis در compose** — مستقل‌اند. compose فقط `app` + ۲ worker.
- **هیچ custom network** جز `coolify` (external) — طبق داک، شبکه‌ی سفارشی routing Traefik را می‌شکند.
- **هیچ مقدار hardcode** — همه `${VAR}`؛ اسرار از تب Coolify. هیچ پسورد/توکن در repo یا image.
- **logها روی stdout/stderr** — supervisord الان همین کار را می‌کند (`/dev/stdout`)؛ حفظ کن.
- `serverVersion=mariadb-11.8.0` در `DATABASE_URL` و نسخه‌ی Resource مستقل MariaDB باید یکی باشند.
- فقط سرویس `app` (`RUN_INIT=1`) migration می‌زند؛ workerها نباید (race).
- image مشترک `clinicpro-app:latest` (app build، workerها reuse) حفظ شود — خرابش نکن.
- entrypoint فعلی wait-for-DB دارد (`doctrine:query:sql "SELECT 1"`)؛ اگر چیزی شکستی، آن را نگه‌دار.
- تغییر صرفاً infra است؛ هیچ controller/Entity عوض نمی‌شود، پس `docs/api/*` نیاز به آپدیت ندارد — فقط `docs/DEPLOY.md`.
- بعد از اتمام، **چک‌لیست نهایی** بده:
  - ✅ Build موفق · ✅ Image Production Ready · ✅ Coolify Compatible · ✅ Compose Compatible
  - ✅ Connect to Predefined Network · ✅ MariaDB External · ✅ Redis External
  - ✅ Security (non-root یا توضیح) · ✅ Performance (opcache/fpm/nginx) · ✅ Healthcheck معتبر
  - ✅ Zero Hardcoded Secret · ✅ Ready for Deployment