clinicpro/docs/deploy-liara-php.md

راهنمای دیپلوی ClinicPro روی لیارا (پلتفرم PHP)

دیپلوی بک‌اند Symfony روی پلتفرم PHP لیارا (نوع برنامه php هنگام «ساخت برنامه‌ی جدید»). اینجا داکری در کار نیست؛ لیارا کد را می‌گیرد، خودش composer install می‌زند و روی Apache + PHP-FPM سرو می‌کند.

مسیر جایگزین (داکر) در docs/deploy-liara.md است. همزمان فقط یک مسیر را نگه دار — هر دو از یک liara.json استفاده می‌کنند.

---

نمای کلی

┌──────────────── Liara private network ─────────────────┐
│                                                        │
│  ┌──────────────────────────────┐   ┌──────────────┐   │
│  │  clinicpro-api  (PHP app)    │   │ MariaDB 11.8 │   │
│  │  • Apache + PHP-FPM (docroot │◄─►│  (managed)   │   │
│  │    = public/)  :80           │   └──────────────┘   │
│  │  • supervisor.conf:          │   ┌──────────────┐   │
│  │     worker-async             │◄─►│    Redis     │   │
│  │     worker-scheduler         │   │  (managed)   │   │
│  └──────────────────────────────┘   └──────────────┘   │
│   disks: jwt / uploads / var-uploads                   │
└────────────────────────────────────────────────────────┘
                  │ :80
                  ▼  https://<domain>

همهٔ پروسه‌ها (وب + هر دو worker) در یک کانتینر اجرا می‌شوند؛ workerها کانتینر جدا ندارند (برخلاف نسخهٔ docker-compose).

---

فایل‌های دخیل (همه ساخته شده‌اند)

فایل	نقش
liara.json	platform: php، php.version: 8.2، documentRoot: public، دیسک‌ها
public/.htaccess	rewrite front-controller سیمفونی روی Apache
liara_pre_build.sh	قبل composer install: ساخت .env مینیمال prod
liara_pre_start.sh	قبل start: انتظار DB، تولید JWT، cache، migration
supervisor.conf	دو worker مسنجر (async + scheduler_default)
liara_php.ini	memory_limit، حجم آپلود، زمان اجرا
.liaraignore	کنترل آپلود (تا public/build آپلود شود، سکرت‌ها مستثنی)
.env.liara.example	مرجع متغیرهای محیطی

---

پیش‌نیاز

npm i -g @liara/cli
liara login

مقادیر آماده:

php -r "echo bin2hex(random_bytes(32)).\"\n\";"   # APP_SECRET
openssl rand -hex 32                               # JWT_PASSPHRASE
ddev exec php docker/gen-cors-env.php              # ALLOWED_FRONTEND_HOSTS + CORS_ALLOW_ORIGIN

---

گام ۱ — build محلی asset‌ها (حیاتی)

پلتفرم PHP لیارا yarn اجرا نمی‌کند و asset‌های React را نمی‌سازد. قبل هر دیپلوی محلی build کن (خروجی در public/build؛ .liaraignore آن را آپلود می‌کند):

ddev exec yarn install --frozen-lockfile
ddev exec yarn build

اگر این مرحله را رد کنی، پنل ادمین /admin لود نمی‌شود.

---

گام ۲ — ساخت دیتابیس و Redis

کنسول لیارا:

1. MariaDB 11.8 بساز (هماهنگ با serverVersion=mariadb-11.8.0).
2. Redis بساز.
3. روی هر دو شبکهٔ خصوصی فعال؛ هاست خصوصی/کاربر/رمز را یادداشت کن.

---

گام ۳ — ساخت برنامهٔ PHP

1. New App → نوع PHP → نسخهٔ 8.2 (پروژه php: >=8.2 می‌خواهد) → شناسه clinicpro-api.
2. آن را به همان شبکهٔ خصوصیِ DB و Redis وصل کن.

---

گام ۴ — ساخت دیسک‌های ماندگار

در صفحهٔ برنامه، بخش Disks، این سه دیسک را با همین نام‌ها بساز (mount از liara.json):

نام	mountTo	محتوا
jwt	/var/www/config/jwt	کلید JWT (نباید هر دیپلوی نو شود)
uploads	/var/www/public/uploads	فایل‌های عمومی
var-uploads	/var/www/var/uploads	فایل‌های خصوصی

⚠️ ریشهٔ اپ فرض شده /var/www. اگر در لاگ مسیر دیگری دیدی، mountTo در liara.json را اصلاح کن.

---

گام ۵ — متغیرهای محیطی

از روی .env.liara.example ست کن (تب Environment یا CLI). یک‌بار روی app؛ workerها همان را می‌گیرند.

liara env set APP_ENV=prod APP_DEBUG=0 --app clinicpro-api
liara env set APP_SECRET=<...> JWT_PASSPHRASE=<...> --app clinicpro-api
liara env set DATABASE_URL="mysql://<user>:<pass>@<db-private-host>:3306/<db>?serverVersion=mariadb-11.8.0&charset=utf8mb4" --app clinicpro-api
liara env set REDIS_URL="redis://:<pass>@<redis-private-host>:6379" --app clinicpro-api
liara env set MESSENGER_TRANSPORT_DSN="redis://:<pass>@<redis-private-host>:6379/messages" --app clinicpro-api
liara env set JWT_SECRET_KEY='%kernel.project_dir%/config/jwt/private.pem' JWT_PUBLIC_KEY='%kernel.project_dir%/config/jwt/public.pem' --app clinicpro-api
liara env set APP_BASE_URL=https://<domain> DEFAULT_URI=https://<domain> --app clinicpro-api
liara env set TRUSTED_PROXIES="10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,127.0.0.1" --app clinicpro-api
liara env set ALLOWED_FRONTEND_HOSTS="<output>" CORS_ALLOW_ORIGIN="<output>" --app clinicpro-api
liara env set API_IR_BASE_URL=https://s.api.ir API_IR_TOKEN=<token> --app clinicpro-api
liara env set REFRESH_TOKEN_TTL=2592000 OTP_TTL=1200 MAX_FILE_SIZE_BYTES=5242880 UPLOAD_DIR=var/uploads --app clinicpro-api

نکته‌ها:

• RUN_INIT را ست نکن — init یک‌بار در liara_pre_start.sh اجرا می‌شود.
• APP_ENV=prod موقع build هم لازم است (composer اسکریپت cache:clear را اجرا می‌کند).
• کلیدهای SMS و درگاه پرداخت از دیتابیس خوانده می‌شوند، نه env.

---

گام ۶ — دیپلوی

از ریشهٔ clinicpro/:

liara deploy

روند خودکار:

1. liara_pre_build.sh → .env مینیمال prod (اگر نبود).
2. composer install (لیارا).
3. liara_pre_start.sh → انتظار DB → تولید JWT (روی دیسک) → warmup → migration.
4. Apache (docroot=public) + supervisor.conf (هر دو worker) بالا می‌آیند.

---

گام ۷ — اتصال دامنه و تأیید

1. بخش Domains: دامنهٔ API را وصل کن، TLS بگیر.
2. سلامت:

   curl -i https://<domain>/health      # باید 200
   

3. workerها:

   # در کنسول/CLI برنامه:
   supervisorctl status                 # worker-async و worker-scheduler = RUNNING
   

4. ورود /admin و تست یک endpoint (تأیید DB/Redis).

---

دیپلوی‌های بعدی

ddev exec yarn build      # اگر assets عوض شد
liara deploy

migrationها خودکار در liara_pre_start.sh اجرا می‌شوند. دیسک‌ها و env حفظ می‌شوند.

---

نگاشت compose → لیارا (PHP platform)

در docker-compose.yml هر worker یک کانتینر جدا بود؛ اینجا هر دو در همان کانتینر با supervisor.conf:

compose	لیارا
سرویس app (php-fpm+nginx)	خود پلتفرم PHP (Apache+PHP-FPM)، docroot=public
worker-async (کانتینر جدا)	[program:worker-async] در supervisor.conf
worker-scheduler (کانتینر جدا)	[program:worker-scheduler] در supervisor.conf
environment: *app-env + RUN_INIT	env روی app؛ init در liara_pre_start.sh
volumes	دیسک‌های liara.json
networks: [coolify]	شبکهٔ خصوصی لیارا
restart/healthcheck	autorestart=true
stop_grace_period: 30s	stopsignal=TERM + stopwaitsecs=30

---

رفع اشکال

نشانه	علت	راه‌حل
پنل /admin سفید/۴۰۴ asset	public/build آپلود نشده	ddev exec yarn build قبل deploy؛ .liaraignore build را مستثنی نکند
کل سایت ۴۰۳/۴۰۴	documentRoot روی public نیست یا .htaccess نیست	documentRoot: public در liara.json + public/.htaccess
Database not reachable after 60s	شبکهٔ خصوصی/DATABASE_URL غلط	DB و app یک شبکه؛ هاست خصوصی را چک کن
توکن‌ها بعد هر دیپلوی باطل	دیسک jwt mount نشده	دیسک jwt → /var/www/config/jwt
worker بالا نمی‌آید / messenger خطای redis	افزونهٔ redis روی پلتفرم نیست	php -m | grep redis؛ نبود → MESSENGER_TRANSPORT_DSN=doctrine://default + کش فایل‌سیستم
build به‌خاطر composer scripts شکست	cache:clear موقع نصب	مطمئن شو APP_ENV=prod ست است؛ در صورت لزوم نصب را --no-scripts کن و همه‌چیز را به liara_pre_start.sh بسپار
خطای CORS از فرانت	CORS_ALLOW_ORIGIN قدیمی	docker/gen-cors-env.php دوباره؛ env به‌روز

---

ریسک‌های شناخته‌شده

• ext-redis: اگر پلتفرم PHP لیارا phpredis نداشته باشد، Redis (cache + messenger) کار نمی‌کند → fallback به Doctrine transport و کش فایل‌سیستم. قبل اتکا verify کن.
• مسیر دیسک: ریشهٔ /var/www فرض است؛ با لاگ واقعی تطبیق بده.
• انتخاب مسیر: یا Docker یا PHP platform — هر دو liara.json را همزمان نگه ندار.