Cara Deploy Next.js dengan PM2 di Ubuntu 24.04 LTS

Next.js adalah framework React yang banyak digunakan untuk membangun aplikasi web modern dengan dukungan server-side rendering, static generation, dan API routes dalam satu project. Panduan ini menjelaskan langkah deploy aplikasi Next.js versi terbaru di Ubuntu 24.04 LTS, menggunakan paket qVM-2, dengan Node.js LTS, PM2 sebagai process manager, dan Nginx sebagai reverse proxy. Pembahasan mencakup instalasi environment server, kustomisasi halaman utama sebagai studi kasus, build project, konfigurasi PM2 agar aplikasi berjalan persisten, konfigurasi Nginx, hingga pemasangan SSL gratis menggunakan Let's Encrypt.

Pengenalan

Next.js adalah framework berbasis React yang menambahkan kemampuan server-side rendering (SSR), static site generation (SSG), dan API routes di atas React, sehingga banyak dipakai untuk aplikasi web yang membutuhkan performa dan SEO yang baik. Berbeda dari aplikasi PHP yang dijalankan langsung oleh web server lewat PHP-FPM, aplikasi Next.js berjalan sebagai proses Node.js tersendiri (default di port 3000). Web server seperti Nginx pada arsitektur ini berperan sebagai reverse proxy, meneruskan request dari domain publik ke proses Node.js tersebut.

PM2 digunakan sebagai process manager untuk menjalankan aplikasi Next.js secara persisten di background, melakukan auto-restart apabila aplikasi crash, mengelola log, dan memastikan aplikasi otomatis berjalan kembali setelah server reboot.

Ubuntu 24.04 LTS dipilih sebagai basis OS karena mendapat dukungan resmi (security update dan bug fix) hingga April 2029, sehingga sesuai digunakan untuk server aplikasi yang membutuhkan masa pakai jangka panjang. Panduan ini ditujukan untuk VPS atau qVM yang baru saja di-deploy (fresh install) dan belum memiliki konfigurasi tambahan apa pun.

Persyaratan

Sebelum memulai deploy, pastikan hal-hal berikut sudah terpenuhi:

Software

• Ubuntu 24.04 LTS, kondisi fresh install (belum ada web server/service lain yang bentrok port)
• Akses root atau user dengan hak sudo
• Koneksi internet untuk mengunduh paket dari repository Ubuntu, dependensi npm, dan sertifikat SSL
• SSH client pada sisi lokal untuk remote ke qVM
• Project Next.js yang akan di-deploy (project baru maupun repository Git yang sudah ada)

Hardware / Spesifikasi VPS qVM

Panduan ini menggunakan paket qVM-2, dengan spesifikasi:

• vCPU: 1 core
• RAM: 2 GiB
• Storage: 50 GiB
• Domain yang sudah diarahkan (A record) ke IP Publik qVM — digunakan untuk konfigurasi reverse proxy dan penerbitan sertifikat SSL

Spesifikasi ini sudah memadai untuk deploy aplikasi Next.js skala kecil hingga menengah. Perlu diperhatikan bahwa qVM-2 hanya memiliki 1 vCPU, sehingga manfaat PM2 cluster mode (menjalankan beberapa instance sekaligus memanfaatkan banyak core) masih terbatas. Untuk aplikasi dengan traffic tinggi atau yang ingin memanfaatkan cluster mode PM2 secara maksimal, disarankan menggunakan paket qVM dengan vCPU lebih banyak.

Tahapan

1. Update dan Upgrade OS Ubuntu 24.04 LTS

Lakukan update dan upgrade pada sistem operasi Ubuntu 24.04 LTS terlebih dahulu, sebelum memulai instalasi service lainnya.

apt update && sudo apt upgrade -y

2. Instalasi Nginx

apt install nginx -y

Aktifkan agar berjalan otomatis saat qVM di-reboot, lalu periksa statusnya:

systemctl enable nginx
systemctl status nginx

Apabila status menunjukkan active (running), Nginx sudah dapat digunakan. Akses http://<IP-qVM> melalui browser untuk memastikan halaman default "Welcome to nginx!" tampil dengan benar.

3. Instalasi Node.js dengan NVM

NVM (Node Version Manager) digunakan untuk menginstal dan mengelola versi Node.js tanpa bergantung pada versi lawas yang disediakan repository Ubuntu, sekaligus mempermudah pergantian versi Node.js di kemudian hari apabila dibutuhkan.

Unduh dan jalankan installer NVM:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.6/install.sh | bash

Muat ulang shell agar perintah nvm dapat langsung digunakan:

source ~/.bashrc

Instal Node.js versi Active LTS terbaru (saat ini Node.js 24.x) dan jadikan sebagai versi default:

nvm install --lts
nvm alias default lts/*

Verifikasi versi Node.js dan npm yang terpasang:

node -v
npm -v

NVM menginstal Node.js pada direktori home milik user yang menjalankan perintah di atas. Pastikan seluruh tahapan berikutnya — instalasi PM2, deploy project, hingga pm2 startup — dilakukan dengan user yang sama, karena PM2 akan mendeteksi path Node.js aktif dari user tersebut.

4. Instalasi PM2

npm install -g pm2

Verifikasi instalasi:

pm2 -v

5. Deploy Project Next.js

Buat direktori project dan buat project Next.js baru dengan versi terbaru:

mkdir -p /var/www
cd /var/www
npx create-next-app@latest nextjs-app

Beberapa prompt interaktif akan muncul. Supaya kode landing page pada tahap 6 langsung kompatibel, gunakan jawaban berikut:

• TypeScript? Yes
• ESLint? Yes
• Tailwind CSS? Yes
• src/ directory? No (opsional, boleh Yes)
• App Router? Yes
• Import alias? biarkan default (tekan Enter)

Apabila project sudah ada di repository Git, gunakan git clone diikuti npm install di dalam direktori project sebagai gantinya — sesuaikan tahap 6 dengan struktur project yang sudah ada.

Pada qVM dengan RAM terbatas (misalnya qVM-2), proses instalasi dependensi maupun build project dapat memakan memori cukup tinggi. Apabila proses gagal karena kehabisan memori, tambahkan swap sementara sebagai penyangga sebelum menjalankan ulang perintah tersebut.

Atur kepemilikan direktori project:

chown -R $USER:www-data /var/www/nextjs-app

6. Studi Kasus: Kustomisasi Halaman Utama

Sebagai studi kasus, ganti halaman utama bawaan Next.js dengan landing page yang menampilkan ringkasan komponen stack ini — Node.js, PM2, dan Nginx — mengikuti tema tutorial yang sedang dibahas.

vim /var/www/nextjs-app/app/page.tsx

Ganti seluruh isinya dengan:

export default function Home() {
  return (
    <main className="min-h-screen bg-slate-950 text-slate-100">
      <section className="bg-gradient-to-br from-indigo-700 via-indigo-500 to-cyan-400 px-6 py-20 text-center text-white">
        <span className="inline-block rounded-full bg-white/15 px-4 py-1.5 text-sm tracking-wide">
          KB Sequel &middot; Landing Page Demo
        </span>
        <h1 className="mt-5 text-4xl font-bold">Deployment Berhasil</h1>
        <p className="mx-auto mt-4 max-w-xl text-lg opacity-95">
          Halaman ini adalah contoh landing page Next.js yang berjalan di atas PM2 dan Nginx reverse proxy, pada paket qVM-2.
        </p>
        <a
          href="#status"
          className="mt-8 inline-block rounded-full bg-white px-8 py-3 font-semibold text-indigo-700"
        >
          Lihat Status &rarr;
        </a>
      </section>

      <section id="status" className="mx-auto max-w-4xl px-6 py-16">
        <h2 className="text-center text-2xl font-semibold">Apa yang Sudah Berjalan?</h2>
        <p className="mt-2 text-center text-slate-400">
          Ringkasan komponen yang sudah dikonfigurasi sampai tahap ini
        </p>
        <div className="mt-10 grid grid-cols-1 gap-6 sm:grid-cols-2">
          <div className="rounded-2xl border border-slate-700 bg-slate-800 p-6">
            <h3 className="font-semibold">Node.js Aktif</h3>
            <p className="mt-1 text-sm text-slate-400">
              Aplikasi Next.js dijalankan di atas Node.js LTS pada port 3000.
            </p>
          </div>
          <div className="rounded-2xl border border-slate-700 bg-slate-800 p-6">
            <h3 className="font-semibold">PM2 Terkelola</h3>
            <p className="mt-1 text-sm text-slate-400">
              Proses berjalan persisten, auto-restart, dan otomatis aktif kembali setelah reboot.
            </p>
          </div>
          <div className="rounded-2xl border border-slate-700 bg-slate-800 p-6">
            <h3 className="font-semibold">Nginx Reverse Proxy</h3>
            <p className="mt-1 text-sm text-slate-400">
              Permintaan dari domain publik diteruskan Nginx ke aplikasi Next.js.
            </p>
          </div>
          <div className="rounded-2xl border border-slate-700 bg-slate-800 p-6">
            <h3 className="font-semibold">Siap Dikustomisasi</h3>
            <p className="mt-1 text-sm text-slate-400">
              Ganti konten halaman ini sesuai kebutuhan project Anda.
            </p>
          </div>
        </div>
      </section>

      <footer className="border-t border-slate-800 px-6 py-8 text-center text-sm text-slate-500">
        <p>Landing page ini adalah contoh deploy Next.js dengan PM2 di atas paket qVM-2.</p>
        <p>&copy; {new Date().getFullYear()} KB Sequel — Semua hak cipta dilindungi.</p>
      </footer>
    </main>
  );
}

Konten diatas merupakan landing page custom sederhana yang sudah kami siapkan sebagai studi kasus pada panduan ini.

7. Build Project Next.js

cd /var/www/nextjs-app
npm run build

Perintah ini menghasilkan folder .next berisi hasil kompilasi production-ready, termasuk optimasi otomatis untuk static asset, code splitting, dan server-side rendering.

8. Jalankan Aplikasi dengan PM2

Secara default, next start menjalankan aplikasi pada port 3000. Jalankan lewat PM2 agar berjalan persisten di background:

pm2 start npm --name "nextjs-app" -- start

Periksa status dan log aplikasi:

pm2 status
pm2 logs nextjs-app

9. Konfigurasi PM2 Startup

Agar aplikasi otomatis berjalan kembali setelah qVM reboot, buat PM2 startup script:

pm2 startup systemd

Perintah di atas akan menampilkan satu baris perintah tambahan yang perlu dijalankan sebagai root — salin dan jalankan perintah tersebut sesuai output yang muncul. pm2 startup secara otomatis mendeteksi path Node.js yang aktif melalui nvm dan menuliskannya langsung ke systemd unit yang dibuat, sehingga tetap berjalan normal meskipun Node.js tidak terpasang secara sistem-wide. Setelah itu, simpan daftar proses PM2 yang sedang berjalan:

pm2 save

10. Konfigurasi Nginx sebagai Reverse Proxy

Nginx berperan sebagai reverse proxy, meneruskan request dari domain publik ke aplikasi Next.js yang berjalan pada port 3000.

vim /etc/nginx/sites-available/nextjs.sequel.web.id.conf

Isi dengan konfigurasi berikut:

server {
    listen 80;
    listen [::]:80;
    server_name nextjs.sequel.web.id;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }

    access_log /var/log/nginx/nextjs-app_access.log;
    error_log /var/log/nginx/nextjs-app_error.log;
}

Header Upgrade dan Connection diperlukan agar koneksi WebSocket (misalnya untuk fitur real-time atau Hot Module Replacement saat development) dapat diteruskan dengan benar melalui Nginx.

Aktifkan dengan symlink ke sites-enabled, lalu uji dan reload konfigurasi:

ln -s /etc/nginx/sites-available/nextjs.sequel.web.id.conf /etc/nginx/sites-enabled/
nginx -t
systemctl reload nginx

11. Uji Akses Aplikasi

Akses http://nextjs.sequel.web.id melalui browser. Pastikan subdomain yang Anda gunakan sudah dipointing ke IP Publik qVM Anda, contohnya seperti gambar di bawah ini

Apabila landing page pada tahap 6 tampil, berarti seluruh stack (Nginx, Node.js, dan PM2) sudah berjalan dengan benar.

Apabila project menggunakan environment variable (file .env.local atau sejenisnya), pastikan file tersebut sudah dikonfigurasi sebelum menjalankan npm run build, karena sebagian nilai environment variable Next.js di-inject saat proses build, bukan hanya saat runtime.

12. Konfigurasi SSL dengan Let's Encrypt

Instal Certbot beserta plugin Nginx-nya untuk otomatisasi penerbitan dan pemasangan SSL.

apt install certbot python3-certbot-nginx -y

Jalankan Certbot dan arahkan ke domain yang digunakan:

certbot --nginx -d nextjs.sequel.web.id

Certbot akan meminta email untuk notifikasi perpanjangan, konfirmasi persetujuan term of service, kemudian menawarkan opsi redirect otomatis dari HTTP ke HTTPS — pilih opsi redirect agar seluruh trafik diteruskan melalui HTTPS. Plugin ini secara otomatis mengedit server block yang sudah dibuat pada tahap 10 untuk menambahkan blok listen 443 ssl beserta path sertifikat.

Sertifikat Let's Encrypt berlaku 90 hari dan diperpanjang otomatis melalui systemd timer bawaan Certbot. Periksa terlebih dahulu apakah mekanisme perpanjangan (renewal) berjalan dengan normal:

certbot renew --dry-run

Setelah tahap ini, https://nextjs.sequel.web.id sudah dapat diakses dengan koneksi terenkripsi SSL.

Kesimpulan

Sampai tahap ini, VPS qVM-2 (1 core, 2 GiB RAM, 50 GiB storage) sudah menjalankan aplikasi Next.js versi terbaru menggunakan Node.js LTS, dikelola oleh PM2 agar berjalan persisten dan otomatis restart apabila terjadi crash atau server reboot, dengan Nginx sebagai reverse proxy di depannya. Studi kasus landing page berhasil menampilkan ringkasan status Node.js, PM2, dan Nginx yang sudah berjalan, dan aplikasi telah diamankan dengan SSL gratis dari Let's Encrypt beserta redirect otomatis ke HTTPS. Konfigurasi ini sudah memadai untuk aplikasi skala kecil hingga menengah dalam lingkungan production; untuk aplikasi yang lebih besar, langkah lanjutan yang disarankan adalah memanfaatkan PM2 cluster mode pada qVM dengan vCPU lebih banyak, mengatur log rotation untuk PM2, memisahkan environment variable per lingkungan (staging/production), dan menyiapkan proses deployment otomatis (CI/CD) untuk pembaruan aplikasi berikutnya.