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. কখন স্ট্যাটিক এক্সপোর্ট বেছে নেবেন?
2. ধাপ ১: Next.js কনফিগারেশন আপডেট
3. ধাপ ২: Environment Variables (.env) সেটআপ
4. ধাপ ৩: লোকাল মেশিনে বিল্ড তৈরি করা
5. ধাপ ৪: cPanel-এ আপলোড ও আনজিপ
6. ধাপ ৫: রাউটিং ও রিফ্রেশ ফিক্স (.htaccess)
7. ধাপ ৬: GitHub Actions দিয়ে অটোমেটিক CI/CD
8. সাধারণ সমস্যা ও সমাধান (Troubleshooting)

---

১. কখন স্ট্যাটিক এক্সপোর্ট বেছে নেবেন?

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) ফাইলটি খুলুন। স্ট্যাটিক এক্সপোর্টের জন্য কনফিগারেশনটি নিচের মতো আপডেট করুন:

/** @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.production
NEXT_PUBLIC_API_BASE_URL=https://api.yourdomain.com/api/v1

3. আপনার কোডে বা Axios/Fetch ফাংশনে এটি ব্যবহার করুন:

// 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();
}

---

ধাপ ৩: লোকাল মেশিনে বিল্ড তৈরি করা

আপনার কোড এডিটর বা টার্মিনালে নিচের কমান্ডটি রান করুন:

npm run build

বিল্ড সফলভাবে শেষ হলে প্রজেক্টে out নামে একটি ফোল্ডার তৈরি হবে। এই ফোল্ডারের ভেতরে আপনার ওয়েবসাইটের সমস্ত জেনারেটেড ফাইল থাকবে:

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. ফাইলে নিচের কোডটুকু যুক্ত করুন:

<IfModule mod_rewrite.c>
  RewriteEngine On
  RewriteBase /
  
  # যদি রিকোয়েস্ট করা ফাইল বা ফোল্ডার সার্ভারে সরাসরি বিদ্যমান থাকে, সেটি সরাসরি লোড হবে
  RewriteCond %{REQUEST_FILENAME} !-f
  RewriteCond %{REQUEST_FILENAME} !-d
  
  # ফাইল না পেলে index.html-এ রিডাইরেক্ট করবে (Client-side routing চালু রাখতে)
  RewriteRule ^ index.html [L]
</IfModule>

৩. ফাইলটি 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 ফাইল তৈরি করে নিচের কোডটি পেস্ট করুন:

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
          <IfModule mod_rewrite.c>
            RewriteEngine On
            RewriteBase /
            RewriteCond %{REQUEST_FILENAME} !-f
            RewriteCond %{REQUEST_FILENAME} !-d
            RewriteRule ^ index.html [L]
          </IfModule>
          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 অভিজ্ঞতা উপভোগ করতে পারবেন।