Cara Deploy Next.js ke VPS Linux Menggunakan Nginx dan PM2

Next.js merupakan salah satu framework JavaScript yang banyak digunakan untuk membangun website modern. Dengan dukungan React, server-side rendering, API routes, dan berbagai fitur optimasi, Next.js dapat digunakan untuk membuat berbagai jenis aplikasi, mulai dari company profile, dashboard, hingga platform bisnis yang kompleks.

Namun, setelah aplikasi selesai dibuat di komputer lokal, langkah berikutnya adalah membuatnya dapat diakses melalui internet. Salah satu pilihan yang cukup fleksibel adalah melakukan deployment ke VPS (Virtual Private Server) Linux.

Dengan VPS, Anda memiliki kendali lebih besar terhadap server, mulai dari instalasi perangkat lunak, konfigurasi keamanan, hingga pengelolaan aplikasi.

Dalam artikel ini, kita akan membahas cara melakukan deployment aplikasi Next.js ke VPS Linux menggunakan tiga teknologi utama:

• Next.js: Framework yang digunakan untuk menjalankan aplikasi.

• PM2: Process manager untuk menjaga aplikasi Node.js tetap berjalan.

• Nginx: Web server yang menerima permintaan pengunjung dan meneruskannya ke aplikasi Next.js.

Panduan ini menggunakan Ubuntu sebagai contoh sistem operasi server. Sebagian besar langkahnya juga dapat disesuaikan untuk distribusi Linux lainnya.

1. Memahami Arsitektur Deployment Next.js

Sebelum mulai melakukan konfigurasi, penting untuk memahami bagaimana ketiga teknologi tersebut bekerja bersama.

Ketika seseorang mengakses website melalui browser, permintaan tersebut pertama kali diterima oleh Nginx. Nginx kemudian meneruskan permintaan ke aplikasi Next.js yang berjalan pada port lokal, misalnya port 3000.

Aplikasi Next.js memproses permintaan tersebut dan mengirimkan hasilnya kembali melalui Nginx kepada pengunjung.

Sementara itu, PM2 bertugas menjaga proses aplikasi Next.js agar tetap berjalan di background. Jika aplikasi mengalami crash, PM2 dapat menjalankannya kembali sesuai konfigurasi.

Gambaran sederhananya:

Pengunjung Website
       |
       | HTTP / HTTPS
       v
     Nginx
   Port 80/443
       |
       | Reverse Proxy
       v
   Next.js App
   Port 3000
       |
       v
      PM2
(Process Manager)

Masing-masing memiliki tanggung jawab berbeda:

Teknologi	Fungsi
Next.js	Menjalankan aplikasi website
PM2	Menjaga aplikasi tetap berjalan
Nginx	Menerima request dan meneruskannya ke Next.js
SSL	Mengamankan komunikasi menggunakan HTTPS

Dengan konfigurasi ini, pengunjung tidak perlu mengakses port 3000 secara langsung. Mereka cukup mengakses domain website melalui HTTP atau HTTPS.

2. Persiapan VPS Linux

Sebelum memulai, pastikan Anda sudah memiliki VPS dengan akses SSH.

Spesifikasi server yang disarankan bergantung pada ukuran aplikasi dan jumlah pengunjung. Untuk aplikasi kecil atau tahap awal, VPS dengan 2 vCPU dan RAM 2 GB dapat menjadi titik awal pengujian, tetapi kebutuhan produksi bisa lebih besar.

Pastikan beberapa hal berikut sudah tersedia:

• VPS dengan sistem operasi Ubuntu.

• Akses SSH menggunakan user yang memiliki hak sudo.

• Domain yang sudah diarahkan ke IP publik VPS.

• Source code aplikasi Next.js.

• Akses ke repository Git jika kode disimpan di GitHub, GitLab, atau layanan sejenis.

Dalam tutorial ini kita menggunakan contoh:

Komponen	Contoh
Sistem operasi	Ubuntu 24.04
Domain	example.com
Direktori aplikasi	/var/www/my-next-app
Port Next.js	3000
Web server	Nginx
Process manager	PM2

Silakan sesuaikan domain dan direktori dengan kebutuhan Anda.

3. Menghubungkan VPS Menggunakan SSH

Buka terminal di komputer Anda, kemudian jalankan perintah berikut:

ssh username@IP_SERVER

Contohnya:

ssh [email protected]

Ganti username dan IP_SERVER sesuai informasi VPS yang Anda miliki.

Setelah berhasil masuk, perbarui daftar paket dan sistem:

sudo apt update
sudo apt upgrade -y

Perintah tersebut digunakan untuk memperbarui daftar paket dan memasang pembaruan yang tersedia.

Selanjutnya, instal beberapa aplikasi pendukung:

sudo apt install -y git curl unzip

Aplikasi tersebut memiliki fungsi sebagai berikut:

• git: Mengambil source code dari repository.

• curl: Mengunduh file atau mengakses layanan melalui URL.

• unzip: Mengekstrak file ZIP.

4. Instalasi Node.js dan NPM

Next.js membutuhkan Node.js untuk menjalankan aplikasi. NPM digunakan untuk mengelola package atau library yang dibutuhkan oleh proyek.

Salah satu cara yang praktis adalah menggunakan NVM (Node Version Manager). Dengan NVM, Anda dapat memasang dan mengganti versi Node.js tanpa harus mengubah instalasi sistem secara manual.

Pasang NVM menggunakan panduan instalasi resmi dari proyek NVM, kemudian buka kembali terminal atau muat ulang konfigurasi shell.

Setelah NVM tersedia, instal versi Node.js LTS yang kompatibel dengan versi Next.js dan dependency proyek Anda.

Contoh menggunakan Node.js 22:

nvm install 22
nvm use 22
nvm alias default 22

Periksa instalasi:

node -v
npm -v

Jika kedua perintah menampilkan nomor versi, berarti Node.js dan NPM sudah siap digunakan.

Catatan: Jangan terpaku pada satu versi Node.js. Periksa kebutuhan versi Node.js pada dokumentasi Next.js dan package yang digunakan oleh aplikasi Anda.

5. Mengambil Source Code Next.js ke VPS

Setelah Node.js tersedia, langkah berikutnya adalah memindahkan source code aplikasi ke server.

Ada beberapa cara yang dapat digunakan, misalnya melalui Git, SFTP, atau mengunggah file ZIP. Dalam tutorial ini kita menggunakan Git.

Buat direktori untuk aplikasi:

sudo mkdir -p /var/www/my-next-app

Atur kepemilikan direktori agar dapat dikelola oleh user yang sedang digunakan:

sudo chown -R $USER:$USER /var/www/my-next-app

Masuk ke direktori tersebut:

cd /var/www/my-next-app

Clone repository:

git clone https://github.com/username/my-next-app.git .

Ganti URL repository dengan repository aplikasi Anda.

Jika repository bersifat private, gunakan metode autentikasi Git yang aman, seperti SSH deploy key atau mekanisme token yang memiliki izin terbatas. Hindari menyimpan password atau token langsung di dalam script deployment.

Setelah proses selesai, periksa isi direktori:

ls -la

Pastikan file penting seperti package.json, konfigurasi Next.js, dan source code aplikasi sudah tersedia.

6. Instalasi Dependency Aplikasi

Setiap proyek Next.js biasanya memiliki daftar dependency di dalam file package.json.

Untuk memasang seluruh dependency, jalankan:

npm ci

Perintah npm ci akan memasang dependency berdasarkan file lock, seperti package-lock.json. Cara ini cocok untuk proses deployment karena menghasilkan instalasi yang lebih konsisten.

Jika proyek tidak memiliki package-lock.json, Anda dapat menggunakan:

npm install

Pastikan proses instalasi tidak menghasilkan error yang belum diselesaikan.

Selanjutnya, periksa bagian scripts pada file package.json. Untuk deployment standar, setidaknya aplikasi perlu memiliki script build dan start.

Contohnya:

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  }
}

Penjelasan:

• dev: Menjalankan aplikasi dalam mode pengembangan.

• build: Membuat hasil build untuk production.

• start: Menjalankan aplikasi menggunakan hasil build production.

Jangan menggunakan npm run dev untuk menjalankan website production. Mode development ditujukan untuk proses pengembangan dan pengujian, bukan untuk melayani pengunjung website secara langsung.

7. Mengatur Environment Variable

Banyak aplikasi Next.js membutuhkan konfigurasi tambahan, seperti koneksi database, API key, secret, dan URL layanan eksternal.

Informasi tersebut biasanya disimpan dalam file environment.

Contohnya:

DATABASE_URL="mysql://user:password@localhost:3306/my_database"
API_SECRET="your-secret-value"
NEXT_PUBLIC_APP_URL="https://example.com"

Buat file .env.production atau file environment yang sesuai dengan konfigurasi aplikasi Anda.

Contoh:

nano .env.production

Kemudian masukkan variabel yang diperlukan.

Perlu diperhatikan bahwa variabel dengan awalan NEXT_PUBLIC_ dapat dimasukkan ke dalam bundle yang dikirim ke browser. Karena itu, jangan pernah menyimpan password database, private API key, atau informasi rahasia lainnya menggunakan awalan tersebut.

Pastikan file environment tidak dapat diakses secara publik dan tidak ikut dimasukkan ke repository Git.

Contoh menambahkan file ke .gitignore:

.env
.env.*
!.env.example

Periksa kembali konfigurasi environment aplikasi sebelum menjalankan proses build. Beberapa nilai environment, khususnya yang menggunakan NEXT_PUBLIC_, dibaca pada saat build dan akan menjadi bagian dari hasil build.

8. Build Aplikasi Next.js untuk Production

Setelah dependency dan environment selesai dikonfigurasi, jalankan perintah:

npm run build

Next.js akan memproses source code dan menghasilkan versi production aplikasi.

Jika build berhasil, biasanya akan muncul direktori .next.

Jangan menghapus direktori tersebut karena berisi hasil build yang dibutuhkan saat aplikasi dijalankan.

Untuk memastikan aplikasi dapat berjalan, lakukan pengujian sementara:

npm run start

Secara default, Next.js akan berjalan pada port 3000.

Buka terminal lain atau jalankan:

curl http://127.0.0.1:3000

Jika aplikasi memberikan respons HTML, berarti server Next.js sudah berjalan.

Hentikan proses pengujian menggunakan Ctrl + C sebelum melanjutkan ke konfigurasi PM2.

9. Instalasi PM2

PM2 adalah process manager untuk aplikasi Node.js. Fungsinya adalah menjaga aplikasi tetap berjalan di background dan membantu menjalankan kembali aplikasi ketika proses mengalami crash.

Instal PM2 secara global:

npm install -g pm2

Periksa instalasi:

pm2 -v

Selanjutnya, jalankan aplikasi Next.js menggunakan PM2:

pm2 start npm --name "my-next-app" -- start

Perintah tersebut menjalankan script start dari package.json dengan nama proses my-next-app.

Aplikasi sekarang berjalan di background dan tidak perlu terus-menerus membuka terminal.

Periksa daftar proses:

pm2 list

Untuk melihat log aplikasi:

pm2 logs my-next-app

Untuk menghentikan aplikasi:

pm2 stop my-next-app

Untuk menjalankan kembali:

pm2 restart my-next-app

Untuk menghapus proses dari daftar PM2:

pm2 delete my-next-app

Membuat konfigurasi PM2 menggunakan ecosystem.config.js

Agar pengelolaan aplikasi lebih rapi, Anda dapat membuat file konfigurasi PM2.

Buat file:

nano ecosystem.config.js

Isi dengan konfigurasi berikut:

module.exports = {
  apps: [
    {
      name: "my-next-app",
      script: "npm",
      args: "start",
      cwd: "/var/www/my-next-app",
      env: {
        NODE_ENV: "production",
        PORT: 3000,
        HOSTNAME: "127.0.0.1"
      }
    }
  ]
};

Penjelasan:

• name: Nama aplikasi pada daftar PM2.

• script: Program yang dijalankan.

• args: Perintah yang diteruskan ke NPM.

• cwd: Direktori aplikasi.

• NODE_ENV: Menandakan aplikasi berjalan dalam mode production.

• PORT: Port yang digunakan Next.js.

• HOSTNAME: Alamat lokal tempat aplikasi menerima koneksi.

Jalankan konfigurasi:

pm2 start ecosystem.config.js

Dengan konfigurasi ini, pengelolaan aplikasi menjadi lebih mudah, terutama ketika Anda memiliki beberapa aplikasi Node.js pada satu VPS.

Membuat PM2 berjalan otomatis setelah server restart

Secara default, proses PM2 perlu dikonfigurasi agar dapat berjalan kembali setelah server reboot.

Jalankan:

pm2 startup

PM2 akan menampilkan perintah tambahan yang perlu dijalankan dengan hak administrator. Salin dan jalankan perintah yang diberikan oleh PM2.

Setelah itu, simpan daftar proses:

pm2 save

Sekarang PM2 dapat memulihkan aplikasi yang tersimpan ketika VPS dinyalakan kembali.

10. Instalasi Nginx

Setelah aplikasi berjalan menggunakan PM2, langkah berikutnya adalah memasang Nginx.

Nginx akan menerima permintaan dari pengunjung melalui port 80 atau 443, kemudian meneruskannya ke aplikasi Next.js pada port 3000.

Instal Nginx:

sudo apt install nginx -y

Jalankan dan aktifkan layanan:

sudo systemctl start nginx
sudo systemctl enable nginx

Periksa status Nginx:

sudo systemctl status nginx

Jika status menunjukkan active (running), berarti Nginx sudah berjalan.

11. Konfigurasi Nginx sebagai Reverse Proxy

Sekarang kita perlu menghubungkan Nginx dengan aplikasi Next.js.

Buat file konfigurasi untuk domain:

sudo nano /etc/nginx/sites-available/my-next-app

Masukkan konfigurasi berikut:

server {
    listen 80;
    listen [::]:80;

    server_name example.com www.example.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;

        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_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Ganti example.com dan www.example.com dengan domain milik Anda.

Penjelasan beberapa bagian konfigurasi:

• listen 80: Nginx menerima koneksi HTTP.

• server_name: Menentukan domain yang menggunakan konfigurasi ini.

• proxy_pass: Meneruskan permintaan ke aplikasi Next.js.

• proxy_set_header: Mengirim informasi request asli kepada aplikasi.

• Upgrade dan Connection: Membantu meneruskan koneksi yang membutuhkan mekanisme upgrade, misalnya WebSocket jika digunakan aplikasi.

Aktifkan konfigurasi:

sudo ln -s /etc/nginx/sites-available/my-next-app /etc/nginx/sites-enabled/

Periksa konfigurasi Nginx:

sudo nginx -t

Jika tidak ada kesalahan, muat ulang Nginx:

sudo systemctl reload nginx

Sekarang coba akses domain melalui browser.

Jika DNS domain sudah mengarah ke IP VPS dan seluruh konfigurasi benar, website Next.js seharusnya sudah dapat diakses melalui Nginx.

Catatan streaming: Jika aplikasi menggunakan streaming response atau fitur yang membutuhkan pengiriman data secara bertahap, periksa konfigurasi buffering Nginx. Untuk kebutuhan tersebut, Anda dapat mempertimbangkan proxy_buffering off pada blok location dan menguji perilakunya sesuai aplikasi.

12. Mengamankan Website dengan SSL atau HTTPS

Website production sebaiknya menggunakan HTTPS agar komunikasi antara browser dan server terenkripsi.

Salah satu cara yang mudah adalah menggunakan Let's Encrypt dengan Certbot.

Instal Certbot:

sudo apt install certbot python3-certbot-nginx -y

Jalankan perintah untuk mendapatkan sertifikat SSL:

sudo certbot --nginx -d example.com -d www.example.com

Ikuti instruksi yang ditampilkan. Jika proses berhasil, Certbot akan membantu memasang konfigurasi SSL pada Nginx.

Setelah itu, akses website menggunakan:

https://example.com

Periksa juga proses pembaruan sertifikat:

sudo certbot renew --dry-run

Perintah tersebut digunakan untuk menguji apakah proses pembaruan otomatis sertifikat dapat berjalan.

Pastikan domain sudah mengarah ke VPS dan port 80 serta 443 dapat diakses dari internet sebelum menjalankan Certbot.

13. Mengatur Firewall VPS

Jangan lupa memastikan firewall hanya membuka port yang diperlukan.

Jika menggunakan UFW pada Ubuntu, periksa statusnya:

sudo ufw status

Jika firewall belum diaktifkan, izinkan koneksi SSH terlebih dahulu agar Anda tidak kehilangan akses ke server:

sudo ufw allow OpenSSH

Izinkan HTTP dan HTTPS:

sudo ufw allow 'Nginx Full'

Kemudian aktifkan firewall:

sudo ufw enable

Periksa kembali:

sudo ufw status

Port 3000 tidak perlu dibuka untuk akses publik karena Nginx dan aplikasi berjalan pada server yang sama. Aplikasi Next.js sudah dikonfigurasi untuk menerima koneksi melalui 127.0.0.1.

Dengan demikian, pengunjung hanya perlu mengakses port 80 dan 443.

14. Cara Update Aplikasi Next.js Setelah Deployment

Deployment bukan pekerjaan yang dilakukan hanya sekali. Ketika developer melakukan perubahan pada aplikasi, server juga perlu diperbarui.

Berikut alur sederhana untuk memperbarui aplikasi yang sudah berjalan.

Masuk ke direktori aplikasi:

cd /var/www/my-next-app

Ambil perubahan terbaru dari repository:

git pull origin main

Pasang dependency jika terdapat perubahan pada package:

npm ci

Build ulang aplikasi:

npm run build

Restart aplikasi menggunakan PM2:

pm2 restart my-next-app --update-env

Periksa log untuk memastikan aplikasi berjalan normal:

pm2 logs my-next-app

Perhatikan bahwa perintah npm ci akan memasang ulang dependency berdasarkan lock file. Jika aplikasi memiliki proses deployment yang lebih kompleks, sebaiknya gunakan direktori release terpisah agar versi aplikasi sebelumnya tetap tersedia ketika proses deployment gagal.

Untuk deployment yang lebih aman, pertimbangkan membuat script otomatis atau menggunakan CI/CD melalui GitHub Actions, GitLab CI, atau Jenkins.

15. Troubleshooting: Masalah yang Sering Terjadi

Ketika pertama kali melakukan deployment, ada beberapa masalah yang cukup sering ditemukan.

A. Website Menampilkan 502 Bad Gateway

Error 502 biasanya berarti Nginx tidak dapat berkomunikasi dengan aplikasi Next.js.

Periksa status PM2:

pm2 list

Lihat log aplikasi:

pm2 logs my-next-app

Periksa apakah Next.js berjalan pada port 3000:

curl http://127.0.0.1:3000

Jika aplikasi tidak berjalan, periksa error pada proses build, environment variable, atau konfigurasi PM2.

Pastikan juga port pada konfigurasi Nginx sama dengan port yang digunakan aplikasi.

B. Website Tidak Bisa Diakses

Jika website tidak dapat dibuka, periksa beberapa hal:

• Apakah domain sudah mengarah ke IP VPS?

• Apakah Nginx berjalan?

• Apakah port 80 dan 443 terbuka?

• Apakah firewall memblokir koneksi?

• Apakah konfigurasi domain pada Nginx sudah benar?

Periksa status Nginx:

sudo systemctl status nginx

Periksa konfigurasi:

sudo nginx -t

C. Aplikasi Berhenti Setelah VPS Restart

Jika aplikasi tidak berjalan setelah server dinyalakan ulang, periksa konfigurasi startup PM2.

Jalankan:

pm2 startup
pm2 save

Pastikan perintah startup yang diberikan PM2 sudah dijalankan dengan benar menggunakan hak administrator dan user yang sesuai.

D. Error Saat Build Next.js

Jika npm run build gagal, periksa pesan error yang muncul.

Beberapa penyebab umum:

• Dependency tidak kompatibel.

• Versi Node.js tidak sesuai.

• Environment variable belum tersedia.

• Kesalahan pada kode aplikasi.

• Kebutuhan memory server tidak mencukupi.

Periksa juga versi Node.js:

node -v

Jika build membutuhkan memory lebih besar, pertimbangkan meningkatkan kapasitas VPS atau menyiapkan proses build di lingkungan lain yang lebih memadai.

E. Website Menampilkan Halaman Lama Setelah Update

Jika aplikasi sudah di-update tetapi halaman masih menampilkan versi lama, periksa apakah build berhasil dan proses PM2 menjalankan aplikasi yang benar.

Jalankan:

npm run build
pm2 restart my-next-app

Jika menggunakan caching tambahan seperti CDN atau reverse proxy lain, periksa juga cache pada layanan tersebut.

16. Tips Keamanan dan Pengelolaan Server

Setelah aplikasi berhasil online, jangan langsung menganggap pekerjaan selesai. Server production perlu dipantau dan dirawat secara berkala.

Berikut beberapa hal yang sebaiknya dilakukan:

1. Jangan menjalankan aplikasi sebagai root. Gunakan user khusus dengan hak akses seperlunya.

2. Jangan membuka port aplikasi ke publik. Jika Nginx berada pada VPS yang sama, gunakan alamat lokal seperti 127.0.0.1.

3. Jaga kerahasiaan environment variable. Jangan memasukkan password, token, dan secret ke repository.

4. Perbarui sistem secara rutin. Lakukan pembaruan keamanan pada Ubuntu, Node.js, Next.js, dan dependency.

5. Pantau log aplikasi. Gunakan pm2 logs dan log Nginx untuk mencari masalah.

6. Buat backup. Simpan backup database, file penting, dan konfigurasi server di lokasi terpisah.

7. Batasi akses SSH dan panel administrasi. Gunakan autentikasi yang kuat dan akses yang diperlukan saja.

8. Pantau penggunaan resource. Periksa RAM, CPU, disk, dan kapasitas VPS secara berkala.

Ingat bahwa PM2 bukan pengganti sistem keamanan dan monitoring server. PM2 membantu menjaga proses aplikasi, sedangkan keamanan tetap membutuhkan pengelolaan server yang baik.

17. Kesimpulan

Deploy Next.js ke VPS Linux menggunakan Nginx dan PM2 merupakan salah satu cara yang fleksibel untuk menjalankan aplikasi web secara mandiri.

Ketiga teknologi tersebut memiliki peran yang berbeda. Next.js menjalankan aplikasi, PM2 menjaga proses aplikasi tetap aktif, dan Nginx menerima permintaan pengunjung serta meneruskannya ke aplikasi.

Dengan konfigurasi yang tepat, Anda dapat menjalankan aplikasi Next.js menggunakan domain sendiri, mengaktifkan HTTPS, mengelola proses aplikasi di background, dan melakukan update tanpa harus selalu menjalankan aplikasi secara manual melalui terminal.

Bagi developer yang ingin memiliki kendali lebih besar terhadap lingkungan deployment, kombinasi Next.js, Nginx, dan PM2 merupakan pilihan yang layak dipelajari.

Namun, jangan hanya berfokus pada keberhasilan website saat pertama kali online. Pastikan juga server memiliki konfigurasi keamanan yang baik, backup rutin, monitoring, dan prosedur deployment yang dapat diandalkan.

Dengan begitu, aplikasi bukan hanya berhasil dipublikasikan, tetapi juga lebih siap untuk digunakan dalam lingkungan production.