Cara Hosting Website Next.js di Panel Pterodactyl dengan PM2 dan Git

Website Next.js bisa jalan 24 jam di panel Pterodactyl tanpa VPS dan tanpa mengetik perintah Linux. Egg Next JS (pm2 + console cmd) menyiapkan pemasangan paket, build production, dan PM2 untuk menjalankan websitemu. Panduan ini membawamu dari server kosong sampai website bisa dibuka lewat domain sendiri, lalu cara memperbarui website tanpa mematikannya.

Yang perlu disiapkan

• Project Next.js yang sudah bisa di-build di komputermu (npm run build tidak error).
• Server dengan egg Next JS (pm2 + console cmd). Belum yakin? Lihat Memilih egg.
• RAM yang cukup. Proses build butuh memori lebih besar daripada saat website sudah berjalan.
• Opsional: repository GitHub atau GitLab.

Cara kerja egg ini

Setiap kali kamu menekan Start atau Restart, egg menjalankan urutan ini:

1. Memeriksa package.json. Kalau tidak ada, server langsung berhenti.
2. Mengenali package manager: pnpm-lock.yaml untuk pnpm, yarn.lock untuk Yarn, selain itu npm.
3. Memasang semua dependency.
4. Menjalankan build (di mode start).
5. Menjalankan website lewat PM2 di port server. Panel menandai server Running saat muncul tulisan Ready in.

Artinya tiap Start atau Restart mengulang install dan build, dan website tidak bisa dibuka selama beberapa menit. Untuk deploy pertama ini wajar. Untuk website yang sudah dipakai pengunjung, pakai cara di bagian Update tanpa downtime di bawah.

Port tidak perlu kamu atur di kode. Egg otomatis menjalankan website di port server kamu.

Langkah 1: Kosongkan folder server

Server baru berisi aplikasi Next.js contoh. Kamu bisa langsung Start untuk melihat apakah semuanya jalan, tapi sebelum memasang project sendiri, folder harus kosong:

1. Klik Stop di tab Console.
2. Buka tab Files, ceklis semua file dan folder, lalu Delete.

Langkah 2: Masukkan project-mu

Metode A: lewat Git (disarankan)

Update jadi gampang karena cukup push lalu jalankan perintah update.

1. Buka tab Startup, lalu isi:
   • Git Repository URL: contoh https://github.com/username/nama-repo.git.
   • Branch: misalnya main. Kosongkan untuk branch bawaan repo.
   • Git Username dan Git Access Token: isi hanya kalau repo private. Token dibuat di GitHub lewat Settings, Developer settings, Personal access tokens.
2. Buka tab Console, lalu klik Start. Karena folder kosong, egg meng-clone repo otomatis, lanjut install dan build.

Git Repository URL hanya dipakai kalau folder server kosong. Kalau masih ada file, clone dilewati.

Metode B: upload manual

1. Di komputer atau handphone, kompres project menjadi .zip tanpa folder node_modules dan .next. Dua folder itu dibuat ulang oleh server.
2. Di tab Files, klik Upload, pilih zip-nya.
3. Ketuk menu pada file zip, pilih Unarchive.
4. Pastikan package.json berada langsung di folder utama. Kalau terekstrak ke dalam folder lain, pindahkan isinya ke luar.

Detail upload dan SFTP ada di Mengunggah file dengan File Manager dan SFTP.

Langkah 3: Atur variabel di tab Startup

Next.js Version dan Package Manager biarkan bawaan (latest dan auto).

Versi Node.js ditentukan oleh Docker Image di tab Startup (Node.js 18 sampai 25). Sesuaikan dengan kebutuhan project-mu, misalnya lewat bagian "engines" di package.json. Versi yang tidak cocok membuat pemasangan paket gagal. Lihat Mengatasi error "Cannot find module".

Kalau project memakai file .env

Buat file .env di folder utama lewat tab Files. Perhatikan dua hal:

• Variabel berawalan NEXT_PUBLIC_ ikut tertanam saat build. Setelah mengubahnya, website harus di-build ulang.
• Kalau nilai mengandung tanda $ (misalnya password database), tulis dengan garis miring terbalik di depannya: \$.

Kalau websitemu memakai database, lihat Cara membuat dan memakai database.

Langkah 4: Jalankan pertama kali

Klik Start, lalu pantau tab Console. Urutan log yang normal:

PM: npm
Installing dependencies...
Build...
Run mode: start
...
Ready in 1.2s

Tunggu sampai berstatus Running. Proses pertama paling lama karena semua paket dipasang.

Langkah 5: Buka websitemu lewat hostname dan port

Alamat bawaan websitemu ada di dua tempat:

• Kartu Address di tab Console.
• Tab Network, di bagian Allocation: kolom hostname (nama server, misalnya node1.contoh.com) dan port (misalnya 5001).

Gabungkan keduanya dengan awalan http://, jadinya http://node1.contoh.com:5001. Alamatnya bisa juga berbentuk IP dan port; fungsinya sama.

Anggap alamat ini seperti localhost. Gunanya untuk memastikan websitemu sudah jalan. Alamat ini hanya bisa dibuka dari perangkat yang sudah mengakses panel servermu, jadi pengunjung lain belum bisa melihat websitemu. Website yang mau dibuka publik harus dihubungkan ke domain (langkah berikutnya).

Langkah 6: Hubungkan domain untuk production

Supaya pengunjung cukup mengetik https://namakamu.com, tanpa nomor port, domainmu perlu diarahkan ke hostname dan port tadi. Caranya ada di panduan khusus:

Cara Memakai Domain Sendiri untuk Website di PterokuDesu dengan Cloudflare (Origin Rule)

Update tanpa downtime

Kalau kamu memakai Restart untuk update/rebuild, website mati selama install dan build. Untuk website yang sudah dipakai pengunjung ada cara yang lebih pas: build saat website masih menyala, lalu ganti ke versi baru dengan pm2 reload.

Aktifkan sekali saja

1. Buka tab Startup, ubah Enable Console Commands (beta) menjadi 1.
2. Restart server satu kali supaya pengaturannya berlaku.

Setelah itu kolom Console bisa dipakai untuk mengetik perintah.

Setiap kali mau update

Lewat Git, ketik di kolom Console lalu tekan Enter:

git pull && npm install && npm run build && pm2 reload app

Lewat upload manual: upload file yang berubah di tab Files, lalu ketik:

npm install && npm run build && pm2 reload app

Pengguna pnpm atau Yarn mengganti npm run build dengan pnpm run build atau yarn build.

Selama build berjalan, website tetap melayani pengunjung. Setelah build selesai, pm2 reload app menggantinya ke versi baru. Tanda && membuat perintah berhenti kalau ada langkah yang gagal, jadi kalau build error, pm2 reload tidak dijalankan dan website yang sedang berjalan tidak diganti.

Mengelola PM2 dari Console

Nama proses website di egg ini selalu app.

Catatan penting

• RAM: build saat website menyala butuh memori lebih besar daripada Restart biasa. Kalau RAM habis, server mati. Lihat Server mati sendiri atau Out of memory.
• Restart server tetap dipakai untuk mengganti Docker Image (versi Node.js) atau mengubah variabel Startup, karena nilainya hanya dibaca saat server menyala.
• Jangan ketik pm2 delete app. Itu menghapus proses website. Server tetap berstatus Running, tapi websitenya mati sampai kamu Restart.
• Peringatan keamanan: dengan opsi ini aktif, siapa pun yang punya akses Console, termasuk sub user yang kamu undang, bisa menjalankan perintah apa saja di dalam server. Biarkan 0 kalau server dipakai orang lain.

Error yang sering muncul

Panduan membaca log ada di Menjalankan, menghentikan, dan merestart server.

Tips

• Coba npm run build di komputermu sebelum upload atau push. Itu menangkap kebanyakan error lebih cepat.
• Jangan upload node_modules dan .next, dan jangan simpan token atau password di repo. Taruh di file .env di server.
• Pakai Schedules dengan hati-hati: restart terjadwal pada egg ini juga membangun ulang website.
• Buat backup sebelum memperbarui versi Next.js atau Node.js.

Pertanyaan yang sering muncul

Apakah update harus Restart server? Tidak. Aktifkan Enable Console Commands, lalu pakai npm run build && pm2 reload app supaya website tidak mati selama build.

Temanku tidak bisa membuka alamat hostname:port websiteku. Kenapa? Alamat itu bekerja seperti localhost: hanya perangkat yang sudah mengakses panel servermu yang bisa membukanya. Untuk akses publik, hubungkan domain.

Bisa pakai pnpm atau Yarn? Bisa. Egg mengenali pnpm lewat pnpm-lock.yaml dan Yarn lewat yarn.lock. Tanpa keduanya, egg memakai npm.

Apa bedanya mode start dan dev? start adalah mode production: di-build dulu, lebih cepat, cocok untuk website publik. dev tanpa build dan ada hot reload, cocok untuk uji coba tapi lebih lambat.

Apakah website tetap hidup kalau crash? Website dijalankan lewat PM2, yang menyalakan ulang prosesnya kalau crash. Kalau server berhenti total, baca log di Console untuk mencari penyebabnya.