Panduan Troubleshooting Server Web ServBay

ServBay mendukung penggunaan Caddy, NGINX, dan Apache sebagai server web default, memberikan Anda fleksibilitas pengembangan lokal. Dalam penggunaan sehari-hari, Anda mungkin menemui masalah seperti situs web tidak bisa diakses, lambat, atau muncul error (misal error 500 Internal Server Error). Panduan ini bertujuan membantu Anda mendiagnosa dan menyelesaikan masalah server web umum di lingkungan ServBay.

Menggunakan Alat Diagnostik Bawaan ServBay

ServBay menyediakan alat diagnostik troubleshooting yang sangat berguna, dapat mendeteksi dan memberitahu Anda tentang masalah konfigurasi maupun layanan yang umum terjadi. Sangat disarankan untuk menggunakan fitur ini terlebih dulu ketika menemui kendala.

Buka aplikasi ServBay, klik menu Troubleshooting di navigasi sebelah kiri untuk masuk ke interface diagnostik bawaan ServBay.

Alat ini akan melakukan pengecekan terhadap status komponen inti ServBay, konflik port, pemeriksaan sintaks konfigurasi, dan memberikan rekomendasi agar Anda cepat menemukan sumber masalah.

Akses Pertama Situs Web Lambat Setelah Migrasi dari MAMP atau Laravel Herd

Jika Anda baru saja berpindah dari MAMP atau Laravel Herd ke ServBay, lalu merasa situs lokal menjadi sangat lambat (>5 detik) saat diakses pertama kali setelah idle, namun akses berikutnya normal. Jika kembali idle lama, akses awal jadi lambat lagi.

Gejala Masalah

Buka Chrome DevTools (tekan F12 atau Cmd+Option+I), pindah ke tab Network, refresh halaman, lalu klik request untuk melihat detail di bagian Timing. Akan tampak waktu DNS Lookup sekitar 5 detik.

(Gambar: Melihat waktu DNS Lookup di tab Network Chrome DevTools)

Penyebab Masalah

MAMP dan Laravel Herd saat instalasi akan memodifikasi pengaturan DNS macOS dan membuat file konfigurasi khusus untuk meroute domain tertentu (misal: *.test, *.local). File-file ini biasanya tersimpan di folder /etc/resolver/.

Meskipun Anda sudah uninstall MAMP atau Laravel Herd, file resolver DNS tersebut sering masih tertinggal. Ketika mengakses situs dengan domain sama (misal .test), macOS terlebih dahulu mencoba query DNS via konfigurasi lama ini—karena service MAMP/Herd DNS sudah tidak ada, query menjadi timeout (sekitar 5 detik), barulah sistem fallback ke DNS default.

Solusi Permasalahan

Ikuti langkah berikut untuk membersihkan sepenuhnya konfigurasi DNS sisa dari MAMP atau Laravel Herd:

1. Uninstall MAMP atau Laravel Herd Secara Benar

Pastikan Anda benar-benar sudah menghapus MAMP atau Laravel Herd menggunakan tools atau script uninstall resminya:

Uninstall MAMP:

• Pakai menu uninstall di aplikasi MAMP
• Atau hapus manual folder /Applications/MAMP dan bersihkan file configuration terkait

Uninstall Laravel Herd:

# Uninstall menggunakan perintah Herd
herd uninstall

# Jika perintah di atas tidak tersedia, hapus manual aplikasi & konfigurasi
rm -rf ~/Library/Application\ Support/Herd
rm -rf ~/.config/herd

2. Hapus File Sisa di Folder /etc/resolver

File konfig DNS bisa tetap tertinggal walau proses uninstall sudah benar. Anda perlu hapus manual file-file di /etc/resolver/ berikut:

# Lihat daftar file di /etc/resolver
ls -la /etc/resolver

# Hapus file resolver tertentu (contoh: test dan local)
sudo rm /etc/resolver/test
sudo rm /etc/resolver/local

# Jika ada resolver lain buatan MAMP/Herd, hapus juga
# Contoh: sudo rm /etc/resolver/herd

File Resolver buatan MAMP/Herd yang umum:

• test - untuk domain *.test
• local - untuk *.local
• herd - khusus Laravel Herd

Catatan: Proses ini butuh hak admin (sudo).

3. Hindari Penggunaan Akhiran Domain *.local

Pada macOS, domain *.local dialokasikan untuk layanan LAN mDNS (Multicast DNS / Bonjour). Jika digunakan untuk situs lokal:

• Bisa konflik DNS
• Akses jadi lambat
• Mendapat perilaku jaringan tak terduga

Saran: Gunakan akhiran domain lain untuk dev lokal, misal:

• .test - khusus untuk lingkungan testing
• .localhost - pasti mengarah ke loopback lokal
• .dev - TLD nyata, tapi sering dipakai dev lokal
• Atau gunakan suffix custom rekomendasi ServBay

4. Bersihkan Cache DNS (opsional)

Setelah perubahan, ada baiknya flush cache DNS agar efek langsung terasa:

# macOS Big Sur (11+) dan lebih baru
sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder

# macOS Catalina (10.15) dan lebih lama
sudo killall -HUP mDNSResponder

5. Verifikasi Perbaikan

Akses kembali situs ServBay Anda:

1. Kunjungi situs lokal di browser
2. Buka Chrome DevTools → tab Network
3. Refresh halaman dan lihat info Timing
4. Pastikan waktu DNS Lookup sudah normal (biasanya < 50ms)

Setelah langkah ini, masalah akses lambat setelah migrasi MAMP/Laravel Herd harusnya teratasi. Jika masih bermasalah, periksa apakah ada software lain (VPN, proxy) yang mengganggu DNS.

Pemeriksaan File Konfigurasi Server Web

Kesalahan file konfigurasi server web adalah penyebab situs gagal diakses paling sering. ServBay menyediakan tools khusus untuk pengecekan sintaks masing-masing server web.

Pemeriksaan Caddyfile

Gunakan perintah validate bawaan Caddy untuk memeriksa kebenaran Caddyfile Anda:

# macOS
/Applications/ServBay/bin/caddy validate -c /Applications/ServBay/etc/caddy/Caddyfile

# Windows
C:\ServBay\bin\caddy.exe validate -c C:\ServBay\etc\caddy\Caddyfile

Jika sintaks benar, akan muncul Valid configuration. Jika error, ada info detail tipe kesalahannya.

Catatan: Perintah caddy validate sering memunculkan INFO/WARN yang berhubungan proses load internal, bukan selalu error. Selama muncul Valid configuration, berarti sintaks benar.

Contoh Error Umum pada Caddyfile:

• File Sertifikat Tidak Ditemukan:

  # Contoh macOS
  2024/12/09 17:24:16.970 INFO using config from file {"file": "/Applications/ServBay/etc/caddy/Caddyfile"}
  ... (INFO/WARN lain) ...
  Error: loading http app module: provision http: getting tls app: loading tls app module: provision tls: loading certificates: open /Applications/ServBay/ssl/private/tls-certs/mail.servbay.host/mail.servbay.host.1crt: no such file or directory
  
  # Contoh Windows
  2024/12/09 17:24:16.970 INFO using config from file {"file": "C:\\ServBay\\etc\\caddy\\Caddyfile"}
  ... (INFO/WARN lain) ...
  Error: loading http app module: provision http: getting tls app: loading tls app module: provision tls: loading certificates: open C:\\ServBay\\ssl\\private\\tls-certs\\mail.servbay.host\\mail.servbay.host.1crt: no such file or directory

  Jika muncul error seperti loading certificates: open xxxxx: no such file or directory, artinya path file sertifikat SSL di Caddyfile tidak ditemukan atau salah. Cek di konfigurasi website Anda path file sertifikat (.crt/.cer/.pem) dan private key (.key) harus sesuai dan file benar-benar ada. ServBay mendukung import manual atau request SSL otomatis lewat ACME—cek juga setting SSL ServBay Anda.

• Kesalahan Path Root Website (Ada Spasi):

  # Contoh macOS
  2024/12/09 17:26:37.371 INFO using config from file {"file": "/Applications/ServBay/etc/caddy/Caddyfile"}
  Error: adapting config using caddyfile: parsing caddyfile tokens for 'root': too many arguments; should only be a matcher and a path, at /Applications/ServBay/etc/caddy/Caddyfile:1388
  
  # Contoh Windows
  2024/12/09 17:26:37.371 INFO using config from file {"file": "C:\\ServBay\\etc\\caddy\\Caddyfile"}
  Error: adapting config using caddyfile: parsing caddyfile tokens for 'root': too many arguments; should only be a matcher and a path, at C:\\ServBay\\etc\\caddy\\Caddyfile:1388

  Error parsing caddyfile tokens for 'root': too many arguments biasanya terjadi jika path root ada spasi. Misal:

  • macOS: root * /Applications/ServBay/www/public web → public web dianggap 2 argumen terpisah
  • Windows: root * C:\ServBay\www\public web → sama

  Solusinya, path yang ada spasi gunakan tanda kutip ganda:

  • macOS: root * "/Applications/ServBay/www/public web"
  • Windows: root * "C:\ServBay\www\public web"

  Tips: Untuk menghindari masalah ini, ganti spasi atau simbol khusus dengan tanda penghubung - atau garis bawah _ (misal: public-folder atau public_dir).

• Error Rule Rewrite Tidak Sesuai Sintaks:

  Menyalin aturan rewrite NGINX langsung ke Caddyfile (tanpa penyesuaian) menyebabkan validasi gagal. Pastikan aturan rewrite sesuai dokumentasi modul Rewrite Caddy atau ikuti panduan migrasi NGINX ke ServBay.

Pemeriksaan Konfigurasi NGINX

Gunakan parameter -t pada NGINX untuk tes sintaks dan validasi file konfigurasi NGINX:

# macOS
/Applications/ServBay/bin/nginx -t

# Windows
C:\ServBay\bin\nginx.exe -t

Jika konfigurasi benar, output:

# macOS
nginx: the configuration file /Applications/ServBay/etc/nginx/nginx.conf syntax is ok
nginx: configuration file /Applications/ServBay/etc/nginx/nginx.conf test is successful

# Windows
nginx: the configuration file C:\ServBay\etc\nginx\nginx.conf syntax is ok
nginx: configuration file C:\ServBay\etc\nginx\nginx.conf test is successful

Jika error, NGINX memberitahu lokasi file dan baris yang bermasalah. Error umum:

1. Sintaks Error: Misal kurang tanda titik koma ;, bracket } tidak cocok, dsb.
2. Kesalahan Path File: Path di include atau direktif lain tidak valid atau file tidak ada.
3. Konflik Port: Port yang didengar sudah dipakai aplikasi lain.

Pemeriksaan Konfigurasi Apache

Gunakan perintah apachectl configtest untuk cek sintaks konfigurasi Apache:

# macOS
/Applications/ServBay/bin/apachectl configtest

# Windows
C:\ServBay\bin\httpd.exe -t

Jika sintaks benar, output Syntax OK. Jika error, akan muncul detail kesalahannya. Error umum:

1. Modul Tidak Bisa Dimuat: Modul (LoadModule) tidak tersedia atau path salah.
2. Error Sintaks File .htaccess: Jika file .htaccess di web root bermasalah, bisa bikin config error atau error akses folder tertentu.
3. Permission Direktori Salah: Aturan di Directory/Files (misal Require, Allow, Deny) bisa mencegah akses file website.

Penanganan Error 500 Internal Server Error

Error 500 menandakan server gagal memenuhi request karena ada kejadian tak terduga. Biasanya terkait script backend seperti PHP, Python, Node.js yang error saat dieksekusi.

Langkah Umum Troubleshooting

Untuk error 500, ikuti langkah di bawah ini:

1. Cek Log Error Server Web: Ini langkah utama. Log error menyimpan detail masalah: script gagal, file hilang, masalah permission, dll.

   macOS:

   • Caddy: /Applications/ServBay/var/logs/caddy/error.log
   • NGINX: /Applications/ServBay/var/logs/nginx/error.log
   • Apache: /Applications/ServBay/var/logs/apache/error.log

   Windows:

   • Caddy: C:\ServBay\var\logs\caddy\error.log
   • NGINX: C:\ServBay\var\logs\nginx\error.log
   • Apache: C:\ServBay\var\logs\apache\error.log

   Cek log paling baru, cari kata error atau critical.

2. Pastikan Service Backend (PHP-FPM) Berjalan: Jika menggunakan PHP, pastikan PHP-FPM sudah aktif.

   ps aux | grep php-fpm

   Cari baris berisi php-fpm: master process atau php-fpm: pool www. Jika tak ditemukan, berarti PHP-FPM tidak jalan/terhenti. Mulai kembali via UI ServBay atau perintah servbayctl.

3. Cek Log Error Script Backend (PHP): Jika error di log server web mengarah ke backend, cek log error bahasa pemrograman terkait.

   Letak log error PHP:

   • macOS: /Applications/ServBay/var/logs/php/php_error.log
   • Windows: C:\ServBay\var\logs\php\php_error.log

   Cari Fatal error, Parse error, Warning, Notice, terutama yang terkait file yang diakses. Untuk dev, aktifkan display_errors agar error detail muncul (edit di php.ini), tapi matikan di produksi.

4. Cek Permission File/Direktori: Service server web jalan sebagai user tertentu, harus cukup hak untuk baca/tulis file situs maupun folder upload/log.

   macOS:

   ls -la /Applications/ServBay/www/your-site/

   Pastikan user server web (umumnya _www) bisa baca folder dan semua file. Untuk upload/log, perlu hak tulis. Atur hak dengan chmod & chown.

   Windows:

   dir C:\ServBay\www\your-site

   Pastikan akun user ServBay punya akses yang cukup ke folder web. Edit di properti file, tab keamanan (security).

Troubleshooting Error 500 pada Server Web Tertentu

• Caddy:

  1. Konfigurasi FastCGI: Pastikan di Caddyfile instruksi php_fastcgi atau reverse_proxy mengarah ke alamat PHP-FPM yang benar (biasanya 127.0.0.1:9000 atau unix:/path/to/php-fpm.sock).
  2. Status PHP-FPM: Pastikan versi PHP yang dipakai & service PHP-FPM di ServBay sudah aktif.
  3. Pengaturan Reverse Proxy: Jika memakai reverse_proxy ke backend lain (Node.js, dsb), cek alamat dan port benar, backend up.

• NGINX:

  1. Setting fastcgi_pass: Di nginx.conf/site config, instruksi fastcgi_pass wajib mengarah ke alamat PHP-FPM yang benar.
  2. client_max_body_size: Untuk upload file besar, jika limit ini terlalu kecil bisa muncul error 500.
  3. Setting try_files: Pastikan instruksi try_files benar sehingga request bisa diteruskan/menemukan index file.

• Apache:

  1. Modul mod_rewrite: Untuk URL rewrite via .htaccess, pastikan modul sudah diaktifkan.
  2. Isi File .htaccess: Syntax salah di .htaccess langsung bikin error 500. Periksa terutama di aturan RewriteRule dsb.
  3. Setting AllowOverride: Aturan ini mengizinkan .htaccess berfungsi; pastikan nilainya All, atau minimal mengaktifkan FileInfo & Limit.

Manajemen Layanan

Setelah edit konfigurasi/server/backend, biasanya perlu restart service supaya perubahan berlaku.

Restart Service

Gunakan perintah berikut untuk restart layanan server web di ServBay:

# Restart Caddy
servbayctl restart caddy -all

# Restart NGINX
servbayctl restart nginx -all

# Restart Apache
servbayctl restart apache -all

Parameter -all memastikan service pendukung (misal PHP-FPM) ikut direstart jika terdeteksi.

Cek Status Service

Untuk melihat status running layanan, pakai:

# Status Caddy
servbayctl status caddy -all

# Status NGINX
servbayctl status nginx -all

# Status Apache
servbayctl status apache -all

Output menunjukkan service berjalan (running), berhenti (stopped), atau status lain. Berguna memastikan service sukses dijalankan.

Langkah Troubleshooting Lanjutan

Jika langkah sederhana belum menyelesaikan masalah, coba langkah lanjutan berikut:

1. Cek Developer Tools Browser: Aktifkan browser DevTools (F12), cek tab Console dan Network. Cermati error JS, status kode network, header response & body. Bisa untuk identifikasi masalah front-end/backend.
2. Gunakan curl -v: Di terminal, jalankan curl -v your-website.servbay.demo supaya log request/response detail, termasuk header, info SSL/TLS, dsb. Ganti domain sesuai aplikasi Anda.
3. Matikan Firewall Sementara: Firewall lokal (di macOS atau software lain) bisa menghalangi koneksi Anda. Coba matikan sementara, kalau sukses, modifikasi aturan agar port ServBay (80, 443, dll) diizinkan.
4. Uji di Browser/Perangkat Lain: Buka situs lewat browser berbeda atau perangkat lain. Jika tetap gagal, bisa jadi masalah global, bukan cache/test perangkat saja.
5. Cek Setting DNS Lokal atau File hosts: Untuk domain custom (bukan localhost atau IP), cek hosts file atau setting DNS supaya nama domain mengarah ke 127.0.0.1 atau ::1.
   • macOS: /etc/hosts
   • Windows: C:\Windows\System32\drivers\etc\hosts

Kesimpulan

Troubleshooting server web adalah tantangan umum dalam pengembangan lokal. Dengan memeriksa sintaks konfigurasi, membaca log error, memastikan service aktif, dan memeriksa hak akses file, mayoritas masalah bisa dituntaskan. Manfaatkan tools diagnostik bawaan ServBay serta command line servbayctl sebagai partner troubleshooting. Jika masalah kompleks, jangan ragu untuk baca dokumentasi ServBay lebih detail atau hubungi tim support teknis untuk bantuan.