# cPanel-এ Next.js (Static Export) ডিপ্লয়মেন্ট ও CI/CD অটোমেশন: সম্পূর্ণ গাইড বর্তমান সময়ে মডার্ন ওয়েব ডেভেলপমেন্টে ফ্রন্টএন্ডের জন্য **Next.js** এবং ব্যাকএন্ডের জন্য আলাদা REST/GraphQL API (Node.js/Express, Django বা Laravel) একটি অত্যন্ত জনপ্রিয় ও স্ট্যান্ডার্ড আর্কিটেকচার। অনেকেই মনে করেন Next.js ডিপ্লয় করতে হলে Vercel বা VPS সার্ভার ছাড়া উপায় নেই। কিন্তু আপনার ফ্রন্টএন্ড যদি ক্লায়েন্ট-সাইড ডেটা ফেচিং এবং আলাদা API সার্ভারের ওপর নির্ভরশীল হয়, তবে কোনো Node.js সার্ভার ছাড়াই **শেয়ার্ড হোস্টিং বা cPanel-এ সম্পূর্ণ ফ্রিতে ও দ্রুততম গতিতে** Next.js স্ট্যাটিক সাইট হিসেবে লাইভ করা সম্ভব। এই ব্লগে আমরা শুরু থেকে শেষ পর্যন্ত ধাপে ধাপে শিখব কীভাবে Next.js প্রজেক্ট স্ট্যাটিক এক্সপোর্ট করবেন, cPanel-এ আপলোড করবেন, পেজ রিফ্রেশ দিলে হওয়া 404 এরর সমাধান করবেন এবং পরিশেষে **GitHub Actions** দিয়ে পুরো প্রক্রিয়াটি অটোমেট (CI/CD) করবেন। --- ## সূচিপত্র 1. [কখন স্ট্যাটিক এক্সপোর্ট বেছে নেবেন?](https://www.google.com/search?q=%23%E0%A7%A7-%E0%A6%95%E0%A6%96%E0%A6%A8-%E0%A6%B8%E0%A7%8D%E0%A6%9F%E0%A7%8D%E0%A6%AF%E0%A6%BE%E0%A6%9F%E0%A6%BF%E0%A6%95-%E0%A6%8F%E0%A6%95%E0%A7%8D%E0%A6%B8%E0%A6%AA%E0%A7%8B%E0%A6%B0%E0%A7%8D%E0%A6%9F-%E0%A6%AC%E0%A7%87%E0%A6%9B%E0%A7%87-%E0%A6%A8%E0%A7%87%E0%A6%AC%E0%A7%87%E0%A6%A8) 2. [ধাপ ১: Next.js কনফিগারেশন আপডেট](https://www.google.com/search?q=%23%E0%A6%A7%E0%A6%BE%E0%A6%AA-%E0%A7%A7-nextjs-%E0%A6%95%E0%A6%A8%E0%A6%AB%E0%A6%BF%E0%A6%97%E0%A6%BE%E0%A6%B0%E0%A7%87%E0%A6%B6%E0%A6%A8-%E0%A6%86%E0%A6%AA%E0%A6%A1%E0%A7%87%E0%A6%9F) 3. [ধাপ ২: Environment Variables (.env) সেটআপ](https://www.google.com/search?q=%23%E0%A6%A7%E0%A6%BE%E0%A6%AA-%E0%A7%A8-environment-variables-env-%E0%A6%B8%E0%A7%87%E0%A6%9F%E0%A6%86%E0%A6%AA) 4. [ধাপ ৩: লোকাল মেশিনে বিল্ড তৈরি করা](https://www.google.com/search?q=%23%E0%A6%A7%E0%A6%BE%E0%A6%AA-%E0%A7%A9-%E0%A6%B2%E0%A7%8B%E0%A6%95%E0%A6%BE%E0%A6%B2-%E0%A6%AE%E0%A7%87%E0%A6%B6%E0%A6%BF%E0%A6%A8%E0%A7%87-%E0%A6%AC%E0%A6%BF%E0%A6%B2%E0%A7%8D%E0%A6%A1-%E0%A6%A4%E0%A7%88%E0%A6%B0%E0%A6%BF-%E0%A6%95%E0%A6%B0%E0%A6%BE) 5. [ধাপ ৪: cPanel-এ আপলোড ও আনজিপ](https://www.google.com/search?q=%23%E0%A6%A7%E0%A6%BE%E0%A6%AA-%E0%A7%AA-cpanel-%E0%A6%8F-%E0%A6%86%E0%A6%AA%E0%A6%B2%E0%A7%8B%E0%A6%A1-%E0%A6%93-%E0%A6%86%E0%A6%A8%E0%A6%9C%E0%A6%BF%E0%A6%AA) 6. [ধাপ ৫: রাউটিং ও রিফ্রেশ ফিক্স (.htaccess)](https://www.google.com/search?q=%23%E0%A6%A7%E0%A6%BE%E0%A6%AA-%E0%A7%AB-%E0%A6%B0%E0%A6%BE%E0%A6%89%E0%A6%9F%E0%A6%BF%E0%A6%82-%E0%A6%93-%E0%A6%B0%E0%A6%BF%E0%A6%AB%E0%A7%8D%E0%A6%B0%E0%A7%87%E0%A6%B6-%E0%A6%AB%E0%A6%BF%E0%A6%95%E0%A7%8D%E0%A6%B8-htaccess) 7. [ধাপ ৬: GitHub Actions দিয়ে অটোমেটিক CI/CD](https://www.google.com/search?q=%23%E0%A6%A7%E0%A6%BE%E0%A6%AA-%E0%A7%AC-github-actions-%E0%A6%A6%E0%A6%BF%E0%A7%9F%E0%A7%87-%E0%A6%85%E0%A6%9F%E0%A7%8B%E0%A6%AE%E0%A7%87%E0%A6%9F%E0%A6%BF%E0%A6%95-cicd) 8. [সাধারণ সমস্যা ও সমাধান (Troubleshooting)](https://www.google.com/search?q=%23%E0%A6%B8%E0%A6%BE%E0%A6%A7%E0%A6%BE%E0%A6%B0%E0%A6%A3-%E0%A6%B8%E0%A6%AE%E0%A6%B8%E0%A7%8D%E0%A6%AF%E0%A6%BE-%E0%A6%93-%E0%A6%B8%E0%A6%AE%E0%A6%BE%E0%A6%A7%E0%A6%BE%E0%A6%A8) --- ## ১. কখন স্ট্যাটিক এক্সপোর্ট বেছে নেবেন? Next.js-এর `output: 'export'` মোডটি আপনার সমস্ত পেজ ও কম্পোনেন্টকে সাধারণ HTML, CSS, JavaScript এবং স্ট্যাটিক অ্যাসেটে রূপান্তর করে। - **কখন উপযুক্ত:** অ্যাডমিন ড্যাশবোর্ড, ইউজার পোর্টাল, ল্যান্ডিং পেজ, অথবা যেকোনো Single Page Application (SPA) যেখানে পেজ লোডের পর ব্রাউজার থেকেই API কল করা হয়। - **সুবিধা:** কোনো Node.js পোর্ট ক্র্যাশ করার ভয় নেই, মেমোরি লিক বা সার্ভার ডাউন হওয়ার ঝুঁকি নেই এবং cPanel Apache/LiteSpeed সার্ভার থেকে আলোর গতিতে ক্যাশ হয়ে পেজ লোড হয়। --- ## ধাপ ১: Next.js কনফিগারেশন আপডেট প্রথমে আপনার প্রজেক্টের রুট ডিরেক্টরিতে থাকা `next.config.js` (বা `next.config.mjs`) ফাইলটি খুলুন। স্ট্যাটিক এক্সপোর্টের জন্য কনফিগারেশনটি নিচের মতো আপডেট করুন: ```javascript /** @type {import('next').NextConfig} */ const nextConfig = { // স্ট্যাটিক HTML ফাইল জেনারেট করার জন্য output: 'export', // স্ট্যাটিক সাইটে ইমেজ অপটিমাইজেশন সার্ভার থাকে না, তাই এটি unoptimized করতে হবে images: { unoptimized: true, }, // পেজগুলোর ডিরেক্টরি অনুযায়ী স্ল্যাশ মেইনটেইন করার জন্য trailingSlash: true, }; module.exports = nextConfig; ``` --- ## ধাপ ২: Environment Variables (.env) সেটআপ যেহেতু স্ট্যাটিক এক্সপোর্টে কোনো সার্ভার রানটাইম থাকে না, তাই বিল্ড চলার সময় এনভায়রনমেন্ট ভ্যারিয়েবলগুলো কোডের ভেতরে সরাসরি ইনলাইন (হার্ডকোড) হয়ে যায়। 1. ক্লায়েন্ট-সাইড থেকে এক্সেস পেতে ভ্যারিয়েবলের নামের শুরুতে অবশ্যই `NEXT_PUBLIC_` থাকতে হবে। 2. প্রজেক্টের রুটে `.env.production` ফাইল তৈরি করুন: ```env # .env.production NEXT_PUBLIC_API_BASE_URL=https://api.yourdomain.com/api/v1 ``` 3. আপনার কোডে বা Axios/Fetch ফাংশনে এটি ব্যবহার করুন: ```typescript // services/api.js const API_URL = process.env.NEXT_PUBLIC_API_BASE_URL; export async function getDashboardData(token) { const res = await fetch(`${API_URL}/dashboard`, { headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json', }, }); return res.json(); } ``` --- ## ধাপ ৩: লোকাল মেশিনে বিল্ড তৈরি করা আপনার কোড এডিটর বা টার্মিনালে নিচের কমান্ডটি রান করুন: ```bash npm run build ``` বিল্ড সফলভাবে শেষ হলে প্রজেক্টে `out` নামে একটি ফোল্ডার তৈরি হবে। এই ফোল্ডারের ভেতরে আপনার ওয়েবসাইটের সমস্ত জেনারেটেড ফাইল থাকবে: ```text out/ ├── _next/ │ └── static/ ├── favicon.ico ├── index.html ├── 404.html └── dashboard/ └── index.html ``` **ম্যানুয়াল আপলোডের জন্য:** `out` ফোল্ডারের ভেতরের সমস্ত ফাইল ও ফোল্ডারগুলো একসাথে সিলেক্ট করে একটি `build.zip` তৈরি করুন। *(পুরো* `out` *ফোল্ডারকে বাইরে থেকে জিপ করবেন না, ভেতরের আইটেমগুলোকে জিপ করবেন।)* --- ## ধাপ ৪: cPanel-এ আপলোড ও আনজিপ 1. আপনার হোস্টিংয়ের **cPanel**\-এ লগইন করুন। 2. **Files** সেকশন থেকে **File Manager** ওপেন করুন। 3. আপনার ডোমেনের জন্য নির্ধারিত রুটে প্রবেশ করুন: - মেইন ডোমেন হলে: `public_html/` - সাবডোমেন হলে: `[subdomain.yourdomain.com/](https://subdomain.yourdomain.com/)` 4. **Upload** বাটনে ক্লিক করে আপনার `build.zip` ফাইলটি আপলোড করুন। 5. আপলোড সম্পন্ন হলে ফাইলটিতে রাইট ক্লিক করে **Extract** চাপুন। --- ## ধাপ ৫: রাউটিং ও রিফ্রেশ ফিক্স (.htaccess) Next.js স্ট্যাটিক সাইটে সবচেয়ে কমন সমস্যা হলো—হোমপেজে থাকা অবস্থায় বিভিন্ন লিংকে ক্লিক করে পেজ ভিজিট করা যায়, কিন্তু কোনো সাব-পেজে (যেমন: `/dashboard`) গিয়ে ব্রাউজারে রিফ্রেশ দিলেই Apache সার্ভার **404 Not Found** রিটার্ন করে। এটি ঠিক করতে Apache রিরাইট রুল যোগ করতে হবে: 1. cPanel File Manager-এ ডোমেনের রুট ফোল্ডারে `.htaccess` নামে ফাইলটি খুলুন। (না দেখলে উপরের ডানপাশে **Settings** > **Show Hidden Files (dotfiles)** চালু করে নিন)। 2. ফাইলে নিচের কোডটুকু যুক্ত করুন: ```apache RewriteEngine On RewriteBase / # যদি রিকোয়েস্ট করা ফাইল বা ফোল্ডার সার্ভারে সরাসরি বিদ্যমান থাকে, সেটি সরাসরি লোড হবে RewriteCond %{REQUEST_FILENAME} !-f RewriteCond %{REQUEST_FILENAME} !-d # ফাইল না পেলে index.html-এ রিডাইরেক্ট করবে (Client-side routing চালু রাখতে) RewriteRule ^ index.html [L] ``` ৩. ফাইলটি Save করুন। এখন যেকোনো পেজে রিফ্রেশ দিলেও আর 404 এরর আসবে না। --- ## ধাপ ৬: GitHub Actions দিয়ে অটোমেটিক CI/CD ম্যানুয়ালি জিপ করে cPanel-এ আপলোড করার ঝামেলা দূর করতে GitHub Actions ব্যবহার করুন। এর ফলে কোড GitHub-এ পুশ করলেই স্বয়ংক্রিয়ভাবে বিল্ড হয়ে cPanel-এ ডিপ্লয় হয়ে যাবে। ### ১. GitHub Secrets কনফিগার করা GitHub রিপোজিটরির **Settings** > **Secrets and variables** > **Actions**\-এ গিয়ে নিচের সিক্রেটগুলো যোগ করুন: - `FTP_SERVER`: আপনার FTP হোস্ট বা সার্ভার আইপি (যেমন: `ftp.yourdomain.com`) - `FTP_USERNAME`: cPanel বা FTP ইউজারনেম - `FTP_PASSWORD`: FTP পাসওয়ার্ড - `NEXT_PUBLIC_API_BASE_URL`: আপনার প্রোডাকশন API URL ### ২. Workflow ফাইল তৈরি করা আপনার প্রজেক্টের রুটে `.github/workflows/deploy.yml` ফাইল তৈরি করে নিচের কোডটি পেস্ট করুন: ```yaml name: Deploy Next.js to cPanel on: push: branches: - main jobs: build-and-deploy: runs-on: ubuntu-latest steps: # রিপোজিটরি ক্লোন - name: Checkout Code uses: actions/checkout@v4 # Node.js এনভায়রনমেন্ট সেটআপ - name: Setup Node.js uses: actions/setup-node@v4 with: node-version: 20 cache: 'npm' # প্যাকেজ ইনস্টল - name: Install Dependencies run: npm ci # প্রোডাকশন বিল্ড - name: Build Next.js Static Files env: NEXT_PUBLIC_API_BASE_URL: ${{ secrets.NEXT_PUBLIC_API_BASE_URL }} run: npm run build # বিল্ড ফোল্ডারে .htaccess তৈরি করা - name: Inject .htaccess File run: | cat << 'EOF' > out/.htaccess RewriteEngine On RewriteBase / RewriteCond %{REQUEST_FILENAME} !-f RewriteCond %{REQUEST_FILENAME} !-d RewriteRule ^ index.html [L] EOF # FTP-র মাধ্যমে cPanel-এ সিঙ্ক করা - name: Sync to cPanel via FTP uses: SamKirkland/FTP-Deploy-Action@v4.3.5 with: server: ${{ secrets.FTP_SERVER }} username: ${{ secrets.FTP_USERNAME }} password: ${{ secrets.FTP_PASSWORD }} protocol: ftps local-dir: ./out/ server-dir: public_html/ dangerous-clean-slate: false ``` এখন থেকে আপনি যখনই কোড `git push origin main` করবেন, GitHub Actions ব্যাকগ্রাউন্ডে বিল্ড করে cPanel-এ লেটেস্ট কোড আপলোড করে দেবে। --- ## সাধারণ সমস্যা ও সমাধান | সমস্যা | কারণ | সমাধান | | --- | --- | --- | | **পেজ রিফ্রেশে 404 Error** | সার্ভার সংশ্লিষ্ট পাথ খুঁজে পাচ্ছে না | রুট ডিরেক্টরিতে `.htaccess` রিরাইট রুল যুক্ত করুন। | | **Next/Image এরর** | স্ট্যাটিক মোডে সার্ভার অপটিমাইজেশন কাজ করে না | `next.config.js`\-এ `images: { unoptimized: true }` যোগ করুন। | | **API URL লোড হচ্ছে না** | ভ্যারিয়েবল ব্রাউজারে এক্সপোজ হয়নি | ভ্যারিয়েবলের নামের শুরুতে `NEXT_PUBLIC_` প্রিফিক্স যুক্ত করুন। | | **GitHub Actions FTP Timeout** | সার্ভার FTPS সাপোর্ট করছে না | Workflow ফাইলে `protocol: ftps`\-এর বদলে `protocol: ftp` ব্যবহার করুন। | --- ## উপসংহার একটি আলাদা ব্যাকএন্ড আর্কিটেকচারের জন্য Next.js-কে স্ট্যাটিক ফ্রন্টএন্ড হিসেবে ডিপ্লয় করা অত্যন্ত কার্যকর ও সাশ্রয়ী একটি পদ্ধতি। এটি একদিকে যেমন হোস্টিং সার্ভারের রিসোর্স বাঁচায়, অন্যদিকে ব্যবহারকারীর ব্রাউজারে অত্যন্ত দ্রুত গতিতে পেজ লোড নিশ্চিত করে। উপরন্তু GitHub Actions ইন্টিগ্রেশনের মাধ্যমে আপনি কোনো বাড়তি খরচ ছাড়াই মডার্ন DevOps অভিজ্ঞতা উপভোগ করতে পারবেন।