Panduan Pemecahan Masalah Server Web ServBay

ServBay mendukung penggunaan Caddy, NGINX, dan Apache sebagai server web default, memberikan Anda fleksibilitas tinggi dalam pengembangan lokal. Saat menggunakan ServBay, Anda mungkin menemui masalah seperti situs tidak dapat diakses, lambat memuat, atau muncul error (seperti 500 Internal Server Error). Panduan ini ditujukan untuk membantu Anda mendiagnosis serta mengatasi masalah umum terkait server web di lingkungan ServBay.

Menggunakan Alat Diagnostik Bawaan ServBay

ServBay menyediakan alat diagnostik bawaan yang sangat fungsional untuk secara otomatis mendeteksi dan memberikan solusi terhadap masalah konfigurasi serta layanan yang umum terjadi. Disarankan untuk selalu menjalankan alat ini terlebih dahulu saat Anda menghadapi kendala.

Buka aplikasi ServBay, lalu klik Diagnostik pada panel navigasi kiri untuk masuk ke tampilan alat diagnostik bawaan.

Alat ini akan memeriksa status komponen inti ServBay, penggunaan port, sintaks file konfigurasi, dan menampilkan saran yang sesuai untuk membantu Anda menemukan sumber masalah dengan cepat.

Memeriksa File Konfigurasi Server Web

Kesalahan dalam file konfigurasi server web sering menjadi penyebab utama website tidak dapat diakses secara normal. ServBay menyediakan alat pemeriksaan sintaks khusus untuk setiap server web.

Pemeriksaan Caddyfile

Gunakan perintah validate bawaan Caddy untuk memverifikasi apakah file konfigurasi Caddyfile Anda sudah benar.

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

Jika sintaks file konfigurasi sudah benar, perintah akan mengembalikan hasil Valid configuration. Jika terdapat kesalahan, Anda akan mendapatkan pesan sesuai tipe error yang terjadi.

Catatan: Perintah caddy validate mungkin menampilkan banyak pesan INFO atau WARN yang umumnya hanya menunjukkan proses internal Caddy, dan belum tentu merupakan kesalahan konfigurasi. Selama hasil akhirnya adalah Valid configuration, maka sintaks sudah benar.

Contoh Kesalahan Umum pada Caddyfile:

• Error file sertifikat tidak ditemukan:

  2024/12/09 17:24:16.970 INFO using config from file {"file": "/Applications/ServBay/etc/caddy/Caddyfile"}
  ... (Pesan INFO/WARN lainnya) ...
  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

  Munculnya error semacam loading certificates: open xxxxx: no such file or directory berarti path file sertifikat SSL pada Caddyfile tidak benar atau file-nya tidak ada. Pastikan Anda sudah menuliskan path file sertifikat (.crt/.cer/.pem) dan private key (.key) dengan benar dan file-nya benar-benar ada di lokasi tersebut. ServBay mendukung impor manual maupun permintaan SSL otomatis lewat ACME, silakan cek pengaturan SSL ServBay Anda.

• Kesalahan path root website (mengandung spasi):

  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

  Error parsing caddyfile tokens for 'root': too many arguments ini biasanya karena path root website Anda mengandung spasi. Misal, penulisan root * /Applications/ServBay/www/public web membuat public web diinterpretasikan sebagai dua argumen berbeda. Solusinya adalah membungkus path yang mengandung spasi dengan tanda kutip ganda ", misal: root * "/Applications/ServBay/www/public web".

  Saran: Hindari penggunaan spasi atau karakter khusus pada nama file dan direktori. Gunakan tanda penghubung - atau garis bawah _ sebagai pemisah kata, misal public-folder atau public_dir.

• Kesalahan aturan rewrite:

  Penggunaan aturan rewrite yang tidak sesuai sintaks Caddy (misal menyalin langsung aturan dari NGINX) akan menyebabkan validasi gagal. Lihat dokumentasi modul Rewrite Caddy atau panduan migrasi dari NGINX ke ServBay untuk memastikan aturan sudah benar.

Pemeriksaan Konfigurasi NGINX

Gunakan parameter -t pada NGINX untuk menguji validitas dan sintaks konfigurasi.

/Applications/ServBay/bin/nginx -t

Jika konfigurasi benar, output-nya:

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

Jika terdapat error, NGINX akan menyoroti letak file dan baris kesalahan. Penyebab umum error konfigurasi NGINX:

1. Kesalahan sintaks: Misal, lupa titik koma ;, atau kurung kurawal } tidak cocok.
2. Path file salah: Path file atau direktori pada instruksi include atau lainnya salah/ tidak ditemukan.
3. Port bentrok: Port yang dipakai sudah digunakan aplikasi lain.

Pemeriksaan Konfigurasi Apache

Gunakan perintah apachectl configtest untuk mengecek sintaks file konfigurasi Apache.

/Applications/ServBay/bin/apachectl configtest

Jika benar, pesan Syntax OK akan ditampilkan. Jika error, Anda akan melihat detail kesalahannya. Penyebab umum error pada konfigurasi Apache:

1. Gagal load modul: Modul (LoadModule) diaktifkan namun file-nya tidak ada atau salah path.
2. Kesalahan sintaks file .htaccess: Error pada .htaccess di root web bisa menyebabkan Apache gagal start atau error pada direktori tertentu.
3. Kesalahan pengaturan permissions direktori: Instruksi seperti Directory atau Files (dengan Require, Allow, Deny) kurang tepat sehingga akses file terblokir.

Penanganan 500 Internal Server Error

500 Internal Server Error adalah kode status HTTP umum yang mengindikasikan server menemukan situasi tidak terduga saat memproses permintaan. Untuk aplikasi web, ini biasanya berarti eksekusi script backend (PHP, Python, Node.js, dsb) gagal.

Langkah Umum Pemecahan Masalah

Saat menemukan error 500, lakukan langkah berikut:

1. Cek log error server web: Ini langkah pertama untuk penelusuran. Biasanya log error memuat detail penyebab error seperti error script, file hilang, atau masalah izin akses.

   • Caddy: /Applications/ServBay/var/logs/caddy/error.log
   • NGINX: /Applications/ServBay/var/logs/nginx/error.log
   • Apache: /Applications/ServBay/var/logs/apache/error.log Cek entri log terbaru, cari kata error atau critical.

2. Pastikan layanan backend (misal PHP-FPM) aktif: Jika website Anda memakai PHP, pastikan PHP-FPM berjalan.

   ps aux | grep php-fpm

   Cari baris yang mengandung php-fpm: master process atau php-fpm: pool www. Jika proses tidak ditemukan, PHP-FPM tidak berjalan/ crash. Jalankan ulang lewat UI ServBay atau perintah servbayctl.

3. Cek log error script backend (misal PHP): Jika ditemukan error FastCGI atau script backend di log server, cek juga log bahasa backend.

   • PHP: /Applications/ServBay/var/logs/php/php_error.log Baca baris yang mengandung Fatal error, Parse error, Warning, atau Notice, terutama berkaitan dengan script yang sedang diakses. Pastikan display_errors non aktif di produksi, namun boleh diaktifkan sementara di pengembangan (set di php.ini) untuk melihat detail error.

4. Cek hak akses file & direktori: Proses server web (misal user _www) butuh akses baca file/direktori website, dan akses tulis untuk folder upload/log.

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

   Pastikan user server web punya hak baca ke root & subfolder website. Untuk upload/log juga perlu akses tulis. Gunakan chmod/chown untuk mengatur hak akses, lakukan dengan hati-hati.

Pemecahan Error 500 Berdasarkan Server Web

• Caddy:

  1. Konfigurasi FastCGI: Pastikan perintah php_fastcgi atau reverse_proxy di Caddyfile mengarah benar ke alamat PHP-FPM (umumnya 127.0.0.1:9000 atau unix:/path/to/php-fpm.sock).
  2. Status PHP-FPM: Pastikan versi PHP dan layanan PHP-FPM yang sesuai aktif di ServBay.
  3. Pengaturan reverse proxy: Jika pakai reverse_proxy ke backend lain (mis. Node.js), cek port/backend yang dituju aktif dan benar.

• NGINX:

  1. Pengaturan fastcgi_pass: Pastikan di nginx.conf atau file konfigurasi website, fastcgi_pass sudah mengarah ke PHP-FPM.
  2. client_max_body_size: Upload file besar gagal (error 500) bisa karena nilai ini terlalu kecil.
  3. Instruksi try_files: Pastikan try_files sudah sesuai agar permintaan dialihkan ke file index atau FastCGI sesuai.

• Apache:

  1. Modul mod_rewrite: Bila pakai URL rewrite via .htaccess, pastikan modul mod_rewrite aktif.
  2. Isi file .htaccess: Error pada aturan .htaccess langsung menyebabkan error 500. Periksa sintaks, khususnya aturan RewriteRule.
  3. Pengaturan AllowOverride: Pastikan di konfigurasi Apache, AllowOverride pada direktori website mengizinkan .htaccess (umumnya di-set All atau minimal mengandung FileInfo dan Limit).

Manajemen Layanan

Setelah mengubah konfigurasi atau memperbaiki masalah backend, seringkali server web atau layanan terkait perlu di-restart agar perubahan berlaku.

Restart Layanan

Gunakan perintah servbayctl restart untuk me-restart layanan server web tertentu.

# Restart layanan Caddy
servbayctl restart caddy -all

# Restart layanan NGINX
servbayctl restart nginx -all

# Restart layanan Apache
servbayctl restart apache -all

Parameter -all akan mencoba juga me-restart layanan pelengkap yang terhubung, misal saat restart Caddy/NGINX/Apache maka PHP-FPM juga di-restart jika FastCGI diaktifkan.

Mengecek Status Layanan

Gunakan perintah servbayctl status untuk melihat status layanan saat ini.

# Lihat status layanan Caddy
servbayctl status caddy -all

# Lihat status layanan NGINX
servbayctl status nginx -all

# Lihat status layanan Apache
servbayctl status apache -all

Output status menunjukkan apakah layanan dalam keadaan running (aktif), stopped (berhenti), atau status lain. Ini membantu Anda memastikan layanan telah berjalan.

Langkah Pemecahan Lanjutan

Jika masalah belum terselesaikan, Anda bisa mencoba langkah-langkah lebih mendalam berikut:

1. Periksa Developer Tools browser: Aktifkan developer tools browser (tekan F12), lalu lihat tab Console dan Network. Cek apakah ada error JavaScript, periksa status respon, header, dan body, sehingga bisa diketahui letak masalah di frontend atau backend.
2. Gunakan perintah curl -v: Di terminal, jalankan curl -v your-website.servbay.demo. Opsi -v menampilkan detail proses request, termasuk header, SSL/TLS, dsb. Ganti your-website.servbay.demo dengan domain faktual website Anda di ServBay.
3. Nonaktifkan firewall sementara: Firewall lokal (seperti bawaan macOS) atau security software pihak ketiga bisa memblokir koneksi masuk. Coba matikan firewall sementara, jika masalah hilang, periksa pengaturan dan pastikan port ServBay (80, 443, dll) diizinkan.
4. Tes di browser/perangkat lain: Coba akses situs di browser dan/atau perangkat berbeda untuk memastikan kendala tidak hanya di satu browser/device (menghindari cache atau setting lokal).
5. Cek DNS lokal atau file hosts: Jika memakai domain kustom (bukan localhost atau IP), pastikan pengaturan /etc/hosts atau DNS sudah benar dan domain mengarah ke 127.0.0.1 atau ::1.

Ringkasan

Mengalami masalah pada server web adalah tantangan umum di pengembangan lokal. Dengan pemeriksaan sistematis mulai dari sintaks konfigurasi, analisis log error, konfirmasi status layanan, hingga pemeriksaan hak akses file, sebagian besar masalah bisa dituntaskan. Tool bawaan ServBay dan perintah servbayctl adalah sahabat andalan Anda. Jika menemui kasus lebih kompleks, jangan ragu membaca dokumentasi ServBay lebih detail atau hubungi tim dukungan teknis untuk bantuan lebih lanjut.