vibe-coding-college-specs/chapters/12-deployment-and-shipping/04-lesson-deploying-with-liara-and-vercel/spec.md

مشخصات درس‌نامه: استقرار عملی پروژه پورتفولیو در لیارا (Liara) و ورسل (Vercel)

• شناسه در سیلابس: L12.5
• فصل: فصل ۱۲: انتشار روی اینترنت (Ch 12)
• نوع محتوا: 📘 درس‌نامه متنی
• زمان تقریبی مطالعه: ۲۰ دقیقه
• پیش‌نیازهای مستقیم: L12.4 (تکامل میزبانی وب و انتخاب PaaS)

---

۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)

دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:

• درک کند (Understand): فرآیند کامل دیپلوی پروژه Next.js به همراه پکیج‌ها و وابستگی‌ها را در دو پلتفرم محبوب لیارا (بومی) و Vercel (بین‌المللی) گام‌به‌گام پیاده کند.
• تحلیل/ارزیابی کند (Evaluate): لاگ‌های زنده زمان ساخت (Build Logs) در داشبورد ابری را بازبینی کرده و خطاهای احتمالی زمان استقرار را تشخیص دهد.
• به‌کار ببندد (Apply): پایگاه داده ابری Supabase را به پروژه مستقرشده متصل کرده و دامنه‌های مجاز بازگشت (Redirect URLs) را در کنسول احراز هویت سوپابیس ثبت نماید.
• ایجاد کند (Create): یک پایپ‌لاین انتشار خودکار از طریق گیت‌هاب ایجاد کند که با هر کامیت، نسخه زنده پورتفولیو به صورت خودکار به‌روزرسانی شود.

---

۲. محدوده و مرزهای محتوا (Scope & Boundaries)

آنچه باید پوشش داده شود (In-Scope):

1. لحظه تاریخی: دیدن پروژه روی یک آدرس عمومی اینترنت!
   • تبدیل کدهای داخل ادیتور به یک سایت زنده اینترنتی که با هر گوشی و لپ‌تاپی باز می‌شود.
2. مسیر اول: استقرار روی پلتفرم ابری بومی لیارا (Liara.ir):
   • ساخت یک برنامه از نوع Next.js در کنسول لیارا با انتخاب ریجن ایران.
   • استقرار با ابزار خط فرمان لیارا (Liara CLI) یا اتصال مستقیم به مخزن گیت‌هاب.
   • پیکربندی بهینه‌ساز کانتینر در next.config.js با ویژگی output: 'standalone' برای کاهش شگفت‌انگیز حجم بیلد.
   • دریافت زیردامنه رایگان و پایدار (مانند my-portfolio.liara.run).
3. مسیر دوم: استقرار روی پلتفرم بین‌المللی Vercel:
   • ورود به vercel.com با حساب گیت‌هاب، انتخاب مخزن پورتفولیو و زدن دکمه Deploy.
   • رصد انیمیشن زنده بیلد کدهای Next.js و دریافت آدرس اختصاصی *.vercel.app.
4. تکمیل زنجیره اتصال به پایگاه داده Supabase:
   • چرا بعد از دیپلوی لاگین با گوگل/گیت‌هاب کار نمی‌کند؟
   • حل قطعی: ثبت آدرس پروداکشن در بخش Authentication \rightarrow URL Configuration \rightarrow Redirect URLs در داشبورد Supabase.
5. قابلیت نجات‌بخش بازگشت آنی (Instant Rollback):
   • اگر تغییری منتشر شد که باگ داشت، چطور با یک کلیک در پنل نسخه قبلی را بدون نیاز به بیلد مجدد برگردانیم.
6. دستورات چندسکویی نصب ابزارهای خط فرمان لیارا و ورسل:
   • نصب در منوهای کشویی ویندوز، مک و لینوکس:
     • نصب Liara CLI: npm install -g @liara/cli
     • نصب Vercel CLI: npm install -g vercel
7. کال‌اوت‌های آموزشی و هشدار کوئرا:
   • کال‌اوت بنفش (<details class="violet">): ویژگی output: 'standalone' در Next.js که فایل‌های node_modules چندصد مگابایتی را به چند مگابایت خالص تبدیل می‌کند.
   • کال‌اوت سبز (<details class="green">): لذت مشاهده اولین پیام موفقیت سبز «Deployment Completed» در داشبورد ابری.
   • کال‌اوت قرمز (<details class="red">): تله آدرس Redirect سوپابیس؛ فراموشی ثبت دامنه جدید در تنظیمات Supabase مانع ورود کاربران به پنل ادمین می‌شود.

آنچه نباید وارد آن شویم (Out-of-Scope):

• پیکربندی متغیرهای محیطی با جزییات کامل (در درس بعدی، ۱۲.۶، به صورت اختصاصی پوشش داده می‌شود).
• خرید و اتصال دامنه اختصاصی شخصی (در درس ۱۲.۷ بررسی می‌شود).

---

۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)

اصطلاح انگلیسی	معادل فارسی مصوب	توضیح یک‌خطی ساده
Standalone Output	خروجی مستقل سرور	قابلیت Next.js برای بسته‌بندی تنها کدهای ضروری در یک فایل سبک و بهینه برای کانتینرها
Build Logs	لاگ‌های فرآیند ساخت	پیام‌های متنی زنده در پنل ابری که جزئیات دانلود پکیج‌ها و کامپایل کدها را نمایش می‌دهند
Instant Rollback	بازگشت آنی به نسخه قبل	امکان سوییچ فوری به نسخه پایدار قبلی سایت در عرض یک ثانیه در صورت بروز مشکل در بیلد جدید
Liara CLI	ابزار خط فرمان لیارا	رابط متنی ترمینال برای ارسال مستقیم فایل‌های پروژه به سرورهای ابری لیارا
Redirect URL Whitelist	لیست سفید آدرس‌های مجاز بازگشت	تنظیمات امنیتی سوپابیس برای ممانعت از بازگشت توکن‌های لاگین به دامنه‌های ناشناس و مشکوک

---

۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)

راهنمای ایجنت نویسنده: تمام تصاویر باید در پوشهٔ images/ ذخیره شده و در جدول تک‌خانه‌ای وسط‌چین درج شوند:

1. تصویر کاور درس: images/cover.png
   • موضوع: نمایش دو سفینه فضایی نئونی مدرن با لوگوهای لیارا و ورسل که کدهای پروژه را به اوج آسمان ابری هدایت می‌کنند.
2. مراحل استقرار در داشبورد لیارا: images/liara-deployment-steps.png
   • موضوع: اسکرین‌شات از مراحل انتخاب پلتفرم Next.js، ساخت برنامه و مشاهده لاگ‌های بیلد موفق در کنسول لیارا.
3. فرآیند Import مخزن در داشبورد Vercel: images/vercel-import-repo-screen.png
   • موضوع: اسکرین‌شات از صفحه اتصال مخزن پورتفولیو از گیت‌هاب در ورسل و زدن دکمه Deploy با جشن پرتاب کاغذهای رنگی (Confetti).
4. تنظیم Redirect URL در کنسول Supabase: images/supabase-redirect-url-setting.png
   • موضوع: اسکرین‌شات از داشبورد Supabase Auth با اضافه شدن آدرس‌های دامنه پروداکشن در فیلد Redirect URLs.

---

۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (README.md)

1. تیتر اصلی: # استقرار عملی پروژه پورتفولیو در لیارا (Liara) و ورسل (Vercel)
2. مقدمه: لحظه‌ای که ماه‌ها برایش تلاش کرده‌اید؛ پورتفولیوی شما آماده تماشای جهان است!
3. جدول کاور درس
4. آماده‌سازی پروژه برای استقرار سرورلس:
   • فعال‌سازی ویژگی طلایی output: 'standalone' در next.config.js.
5. آموزش عملی استقرار در لیارا (میزبانی پایدار بومی):
   • گام ۱: ساخت اکانت در Liara.ir و ورود به پنل.
   • گام ۲: ساخت برنامه جدید از نوع Next.js.
   • گام ۳: استقرار با کامند liara deploy در ترمینال یا اتصال اتوماتیک گیت‌هاب.
   • گام ۴: مشاهده لاگ‌های اجرای کانتینر و دریافت لینک اختصاصی *.liara.run.
6. آموزش عملی استقرار در Vercel (استاندارد جهانی):
   • ورود با گیت‌هاب، انتخاب ریپازیتوری، زدن دکمه Deploy و تماشای بیلد خودکار.
7. هماهنگ‌سازی پایگاه داده Supabase با آدرس پروداکشن جدید:
   • ثبت نشانی جدید سایت در لیست سفید Redirect URLs کنسول سوپابیس برای کارکرد بی‌نقص ورود ادمین.
8. جعبه ابزار خروج اضطراری: قابلیت Instant Rollback:
   • چگونه در کمتر از ۵ ثانیه اشتباهات ناخواسته را در پنل به نسخه سالم قبلی برگردانیم.
9. دستورات چندسکویی نصب و ورود به CLIهای لیارا و ورسل:
   • منوی کشویی سه‌گانه برای ویندوز، مک و لینوکس:
     • Windows (PowerShell):

       npm install -g @liara/cli vercel
       liara login
       

     • macOS (Terminal):

       npm install -g @liara/cli vercel
       liara login
       

     • Linux (Bash):

       npm install -g @liara/cli vercel
       liara login
       

10. باکس نکته Quera (<details class="violet">): اهمیت ممیزی حافظه رم اختصاص‌یافته در پلن‌های لیارا (پلن پایه ۲۵۶ مگابایت یا ۵۱۲ مگابایت برای Next.js).
11. باکس هشدار Quera (<details class="red">): عدم تعریف متغیرهای محیطی در پنل ابری منجر به خطای ۵۰۰ یا صفحه سفید در پروداکشن می‌شود (موضوع درس بعد).
12. باکس رضایت‌بخش Quera (<details class="green">): تست باز کردن آدرس عمومی سایت روی گوشی موبایل خارج از شبکه وای‌فای خانه و مشاهده کارکرد بدون نقص آن.
13. جمع‌بندی درس‌نامه: اجرای موفق اولین دیپلوی زنده؛ ورود به مبحث حیاتی تنظیم متغیرهای محیطی پروداکشن در پنل‌های ابری در درس بعدی.

---

۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)

• مراحل استقرار گام‌به‌گام در هر دو پلتفرم لیارا و ورسل به صورت تصویری و متنی شرح داده شود.
• تنظیم کلیدی output: 'standalone' در فایل کانفیگ Next.js آموزش داده شود.
• رفع باگ رایج Redirect URL در احراز هویت Supabase به طور عملی گنجانده شود.
• دستورات خط فرمان Liara CLI در قالب منوهای چندسکویی ارائه گردد.