# نصب Arcopet Bot Phase 3.1.0 روی cPanel

این فایل روش تک‌برنامه‌ای را توضیح می‌دهد. برای Production و جداسازی پنل محافظت‌شده از FastAPI عمومی، از `CPANEL_SPLIT_DEPLOYMENT_FA.md` استفاده کنید.

این بسته شامل Journey Builder، دارک‌مود، Website Chat Widget و اتصال Read-only به WooCommerce است و برای **Setup Python App / Python Selector** و Phusion Passenger آماده شده است.

## ۱. ساخت برنامه Python

در cPanel وارد **Setup Python App** شوید و این مقادیر را ثبت کنید:

- Python version: `3.11` یا جدیدتر
- Application root: برای مثال `arcopet_bot`
- Application URL: برای مثال `https://cdn.arcopet.com/bot`
- Application startup file: `cpanel_app.py`
- Application entry point: `application`

نکته مهم: در فیلد Startup، نام `passenger_wsgi.py` را وارد نکنید. CloudLinux خودش این فایل واسط را مدیریت می‌کند و انتخاب همان نام می‌تواند باعث Import شدن فایل از داخل خودش و خطای `RecursionError` شود.

از نسخه `3.0.0` Adapter داخل Worker ساخته می‌شود تا Fork داخلی Passenger باعث انتظار بی‌پایان و خطای 504 پراکسی نشود.

اگر برنامه را روی زیردامنه مستقل نصب می‌کنید، Application URL می‌تواند ریشه همان زیردامنه باشد.

## ۲. آپلود فایل‌ها

محتویات ZIP را داخل **Application root** آپلود و Extract کنید. خود پوشه بیرونی ZIP را داخل Application root تکرار نکنید؛ فایل `cpanel_app.py` باید مستقیماً در ریشه برنامه دیده شود.

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

در بخش Environment variables برنامه این مقادیر را اضافه کنید:

    ARCO_BOT_BASE_PATH=/bot
    ARCO_APP_MODE=all
    ARCO_BOT_DB=data/arcopet_bot.sqlite3
    ARCO_PUBLIC_BASE_URL=https://chat.arcopet.com
    ARCO_BOT_ALLOWED_ORIGINS=https://arcopet.com,https://www.arcopet.com
    ARCO_ADMIN_PASSWORD=یک-رمز-قوی-برای-پنل
    ARCO_SECRET_KEY=یک-رشته-تصادفی-طولانی-و-غیرقابل-حدس
    ARCO_WC_BASE_URL=https://arcopet.com
    ARCO_WC_CONSUMER_KEY=ck_READ_ONLY_KEY
    ARCO_WC_CONSUMER_SECRET=cs_READ_ONLY_SECRET
    ARCO_WC_TIMEOUT=10

- مقدار `ARCO_BOT_BASE_PATH` باید دقیقاً با مسیر Application URL یکی باشد.
- برای `https://cdn.arcopet.com/bot` مقدار `/bot` است.
- اگر برنامه روی ریشه یک زیردامنه مثل `https://bot.arcopet.com` نصب شد، مقدار را خالی بگذارید یا `/` وارد کنید.
- مسیر دیتابیس می‌تواند همین مقدار پیش‌فرض باقی بماند. پوشه `data` باید برای کاربر cPanel قابل‌نوشتن باشد.
- `ARCO_BOT_ALLOWED_ORIGINS` دامنه‌هایی است که اجازه استفاده از Widget API را دارند.
- `ARCO_ADMIN_PASSWORD` رمز ورود به پنل مدیریت است.
- `ARCO_SECRET_KEY` باید یک متن تصادفی طولانی و متفاوت از رمز ورود باشد.

## ۴. نصب وابستگی‌ها

در صفحه برنامه، فایل `requirements.txt` را انتخاب و **Run Pip Install** را اجرا کنید. اگر این دکمه وجود ندارد، دستور فعال‌سازی Virtualenv که خود cPanel نمایش می‌دهد را در Terminal اجرا کنید و سپس:

    pip install -r requirements.txt

## ۵. راه‌اندازی

روی **Restart** بزنید و سپس این آدرس‌ها را بررسی کنید:

    https://cdn.arcopet.com/bot/
    https://cdn.arcopet.com/bot/api/health
    https://cdn.arcopet.com/bot/docs
    https://cdn.arcopet.com/bot/widget.js

در Health Check باید مقدار `"ok": true` دیده شود.

## ارتقا از فاز ۱

1. ابتدا از فایل `data/arcopet_bot.sqlite3` نسخه پشتیبان بگیرید.
2. محتوای ZIP فاز ۳ را روی فایل‌های قبلی Extract و Overwrite کنید.
3. متغیرهای محیطی جدید بالا را ثبت کنید.
4. دوباره **Run Pip Install** و سپس Restart را اجرا کنید.

فایل دیتابیس داخل ZIP نیست؛ Journeyهای قبلی حذف نمی‌شوند و جدول تنظیمات Widget خودکار ساخته می‌شود.

## نصب ویجت روی WordPress

پس از ورود به پنل، بخش **ویجت سایت** را باز و تنظیمات را ذخیره کنید. سپس کد نصب نمایش‌داده‌شده را در Footer سایت قرار دهید:

    <script src="https://cdn.arcopet.com/bot/widget.js" defer></script>

ویجت فقط نسخه Published مربوط به Journey انتخاب‌شده را اجرا می‌کند.

## نکته مهم درباره Directory Privacy

در نصب تک‌برنامه‌ای روی کل مسیر `/bot` از Directory Privacy استفاده نکنید؛ در این صورت WordPress نمی‌تواند `widget.js` و API عمومی چت را دریافت کند و خطای 401 ایجاد می‌شود. در استقرار دو اپ، Folder Protection فقط روی اپ Admin باقی می‌ماند.

## خطاهای رایج

### صفحه پیش‌فرض It works نمایش داده می‌شود

Startup file یا Entry point اشتباه است. باید به‌ترتیب `cpanel_app.py` و `application` باشند. بعد از اصلاح Restart کنید.

### خطای RecursionError در passenger_wsgi.py

در **Setup Python App** مقدار Application startup file را از `passenger_wsgi.py` به `cpanel_app.py` تغییر دهید، Save کنید و سپس Restart بزنید. فایل `passenger_wsgi.py` واسط داخلی Passenger است و نباید خودش به‌عنوان Startup انتخاب شود.

### CSS یا درخواست‌های API خطای 404 می‌دهند

مقدار `ARCO_BOT_BASE_PATH` با مسیر Application URL برابر نیست. برای مسیر `/bot` همین مقدار را وارد کنید و Restart بزنید.

### خطای Permission denied برای دیتابیس

از File Manager مطمئن شوید پوشه `data` متعلق به کاربر cPanel و قابل‌نوشتن است. دیتابیس را داخل `public_html` قرار ندهید؛ Application root بهتر است بیرون از آن باشد.

### خطای No module named a2wsgi یا fastapi

نصب `requirements.txt` کامل نشده است. دوباره **Run Pip Install** را اجرا و سپس برنامه را Restart کنید.

## امنیت

پنل صفحه ورود داخلی و Cookie امن دارد. حتماً `ARCO_ADMIN_PASSWORD` و `ARCO_SECRET_KEY` را در cPanel تعریف کنید، HTTPS را فعال نگه دارید و دامنه‌های مجاز را در `ARCO_BOT_ALLOWED_ORIGINS` محدود کنید. کلید WooCommerce باید فقط Read-only باشد و در هر دو Python App صرفاً به‌صورت Environment Variable ثبت شود.
