Guida alla Risoluzione dei Problemi del Server Web ServBay

ServBay supporta Caddy, NGINX e Apache come server web predefiniti, offrendo un ambiente di sviluppo locale flessibile. Durante l’utilizzo, potresti incontrare problemi come siti web non accessibili, caricamenti lenti o errori (come l’errore interno 500). Questa guida ti aiuta a diagnosticare e risolvere le problematiche più comuni legate ai server web nell’ambiente ServBay.

Utilizzare lo strumento integrato di diagnostica ServBay

ServBay offre un strumento di diagnostica avanzato che rileva e segnala automaticamente i problemi di configurazione e di servizio più frequenti. Si consiglia vivamente di utilizzarlo come primo passo in caso di problemi.

Apri l’app ServBay e clicca su Diagnostica nella barra di navigazione a sinistra per accedere all’interfaccia dedicata.

Questo tool verifica lo stato dei componenti principali di ServBay, l’occupazione delle porte, la sintassi dei file di configurazione e fornisce suggerimenti e raccomandazioni per individuare rapidamente la causa del problema.

Sito lento dopo la migrazione da MAMP o Laravel Herd

Se hai migrato da MAMP o Laravel Herd a ServBay e noti che il primo accesso al sito dopo un periodo di inattività richiede più di 5 secondi per caricare, ma i successivi accessi risultano rapidi, e ogni ulteriore pausa riporta il rallentamento iniziale, questo è un problema noto.

Sintomi

Aprendo gli strumenti per sviluppatori di Chrome (premi F12 o Cmd+Option+I), vai al tab Network. Dopo aver aggiornato la pagina, controllando i dettagli delle richieste nella sezione Timing, noterai che la colonna DNS Lookup indica circa 5 secondi di attesa.

(Immagine: visualizzazione del tempo DNS Lookup nel tab Network di Chrome DevTools)

Causa

MAMP e Laravel Herd modificano forzatamente le impostazioni DNS di macOS creando file di configurazione speciali per la risoluzione di domini specifici (*.test, *.local, ecc.) nella cartella /etc/resolver/.

Anche dopo la disinstallazione di MAMP o Laravel Herd, questi file possono restare nel sistema. Quando visiti siti con lo stesso suffisso (ad esempio .test), macOS prova a risolverli tramite questi vecchi resolver, ma poiché i servizi DNS di MAMP/Herd non sono più attivi, la richiesta va in timeout (tipicamente dopo 5 secondi), dopodiché il sistema passa alla configurazione DNS predefinita.

Soluzione

Segui questi passi per rimuovere definitivamente le configurazioni DNS residue di MAMP o Laravel Herd:

1. Disinstalla correttamente MAMP o Laravel Herd

Se non lo hai già fatto, usa gli appositi programmi di disinstallazione o script forniti dagli sviluppatori per una rimozione completa:

Disinstallazione MAMP:

• Usa la funzione di disinstallazione integrata nell’app MAMP
• Oppure elimina manualmente la cartella /Applications/MAMP e i file correlati

Disinstallazione Laravel Herd:

# Comando di disinstallazione ufficiale di Herd
herd uninstall

# Se il comando non è disponibile, elimina manualmente la app e le configurazioni
rm -rf ~/Library/Application\ Support/Herd
rm -rf ~/.config/herd

2. Elimina i file residui nella cartella /etc/resolver

Anche dopo la disinstallazione, i file di configurazione dei resolver DNS nella cartella /etc/resolver/ possono rimanere. Eliminali manualmente:

# Visualizza i file nella cartella /etc/resolver
ls -la /etc/resolver

# Rimuovi i file di resolver specifici (ad esempio test e local)
sudo rm /etc/resolver/test
sudo rm /etc/resolver/local

# Elimina anche altri file creati da MAMP/Herd se presenti
# Esempio: sudo rm /etc/resolver/herd

I file tipici creati da MAMP/Herd sono:

• test - per i domini *.test
• local - per i domini *.local
• herd - specifico per Laravel Herd

Nota: Per cancellare questi file, servono i permessi di amministratore (sudo).

3. Evita il suffisso *.local nei nomi di dominio

macOS riserva il suffisso *.local per il servizio mDNS (Bonjour) della rete locale. Usarlo per lo sviluppo locale può causare:

• Conflitti nel DNS
• Lentezza nell’accesso
• Comportamenti di rete imprevisti

Consigli:

• Utilizza altri suffissi come .test (TLD riservato per test), .localhost (risolve sempre sull’indirizzo locale), .dev (TLD reale ma spesso usato nello sviluppo), oppure adotta i suffissi personalizzati raccomandati da ServBay.

4. Svuota la cache DNS (opzionale)

Dopo aver cancellato i file, svuota la cache DNS per applicare subito le modifiche:

# macOS Big Sur (11) e versioni successive
sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder

# macOS Catalina (10.15) e precedenti
sudo killall -HUP mDNSResponder

5. Verifica la risoluzione

Dopo la pulizia, accedi nuovamente al tuo sito ServBay:

1. Vai sul sito locale dal browser
2. Apri DevTools di Chrome → tab Network
3. Aggiorna la pagina e osserva la sezione Timing
4. Verifica che il tempo DNS Lookup sia inferiore a 50ms

Questi passaggi dovrebbero risolvere la lentezza del primo accesso dopo la migrazione da MAMP o Laravel Herd. Se il problema persiste, verifica la presenza di altri software di terze parti (VPN, proxy) che possono interferire con la risoluzione DNS.

Verifica dei file di configurazione del server web

Errori nei file di configurazione sono una delle cause più comuni di malfunzionamento dei siti web. ServBay offre strumenti dedicati per verificare la sintassi delle configurazioni di ogni server web.

Controllo del Caddyfile

Utilizza il comando validate di Caddy per verificare la correttezza del Caddyfile.

# 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

Se la sintassi è corretta, il comando restituisce Valid configuration. In caso di errori, vengono mostrati messaggi specifici in base al tipo di problema.

Nota: Il comando caddy validate può generare molti messaggi INFO o WARN, relativi ai processi interni di caricamento di Caddy. Questi non indicano necessariamente errori di configurazione. Se appare Valid configuration alla fine, la sintassi è corretta.

Errori tipici del Caddyfile:

• Certificato SSL non trovato:

  # Esempio macOS
  2024/12/09 17:24:16.970 INFO using config from file {"file": "/Applications/ServBay/etc/caddy/Caddyfile"}
  ... (altri messaggi INFO/WARN) ...
  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
  
  # Esempio Windows
  2024/12/09 17:24:16.970 INFO using config from file {"file": "C:\\ServBay\\etc\\caddy\\Caddyfile"}
  ... (altri messaggi INFO/WARN) ...
  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

  Errori tipo loading certificates: open xxxxx: no such file or directory indicano che nel tuo Caddyfile il percorso del certificato SSL è errato o il file non esiste. Assicurati che gli indirizzi dei certificati (.crt, .cer, .pem) e delle chiavi (.key) siano corretti e che i file siano effettivamente presenti. ServBay supporta l’importazione manuale e l’automazione ACM per i certificati: verifica le relative impostazioni SSL.

• Percorso della root del sito non valido (con spazi):

  # Esempio 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
  
  # Esempio 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

  L’errore parsing caddyfile tokens for 'root': too many arguments si verifica spesso se il percorso della directory contiene spazi. Ad esempio:

  • macOS: root * /Applications/ServBay/www/public web — public web viene interpretato come due parametri separati
  • Windows: root * C:\ServBay\www\public web — lo stesso discorso

  La soluzione è racchiudere il percorso tra virgolette:

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

  Suggerimento: Evita spazi o caratteri speciali nei nomi di file e directory. Meglio usare trattini - o underscore _, es: public-folder o public_dir.

• Errore nelle regole Rewrite:

  Le regole di Rewrite copiate da NGINX o non conformi alla sintassi di Caddy causeranno errori di validazione. Consulta la documentazione ufficiale delle direttive rewrite di Caddy e la guida ServBay per la migrazione da NGINX a ServBay.

Verifica della configurazione NGINX

Usa l’opzione -t di NGINX per testare la sintassi e la validità della configurazione.

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

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

Se la configurazione è ok:

# 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

Se ci sono errori, NGINX indica il file e la riga. Errori comuni:

1. Errori di sintassi: Ad esempio, punto e virgola mancante, parentesi graffe non abbinate.
2. Percorsi di file errati: Percorsi inesistenti nei parametri include o altre direttive.
3. Conflitto di porte: La porta di ascolto è occupata da altri servizi.

Controllo configurazione Apache

Utilizza il comando apachectl configtest per verificare la sintassi del file di configurazione Apache.

# macOS
/Applications/ServBay/bin/apachectl configtest

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

Se la sintassi è corretta, appare Syntax OK. In caso contrario, vengono mostrati dettagli dell’errore. Problemi comuni:

1. Modulo non caricato: Moduli (LoadModule) non esistenti o con percorsi errati.
2. Errori nel file .htaccess: La presenza di errori in .htaccess può far fallire la verifica o portare ad errori su directory specifiche.
3. Permessi erronei su directory: Impostazioni di Directory, Files con restrizioni (Require, Allow, Deny) che bloccano l’accesso.

Gestione degli errori 500 Internal Server Error

L’errore HTTP 500 indica che il server ha incontrato un problema imprevisto durante la richiesta — tipicamente dovuto a script lato backend (PHP, Python, Node.js, ecc.) che hanno fallito.

Procedura generale di diagnosi

Quando vedi un errore 500:

1. Controlla i log degli errori del server web: È il primo passaggio. Nei log trovi dettagli su script corrotti, permessi mancanti, file inesistenti, ecc.

   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

   Controlla le righe più recenti e cerca voci come error o critical.

2. Verifica che il backend (PHP-FPM, ecc.) sia attivo: Se il sito usa PHP, assicurati che PHP-FPM sia avviato.

   ps aux | grep php-fpm

   Cerca righe con php-fpm: master process o php-fpm: pool www. Se non ci sono, PHP-FPM è spento o crashato. Riavvialo da UI ServBay o col comando servbayctl.

3. Controlla i log degli errori dello script/backend (PHP): Se nel log del web server trovi errori FastCGI o script, controlla anche il log degli errori PHP.

   Log errori PHP:

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

   Ricerca messaggi tipo Fatal error, Parse error, Warning, Notice relativi ai file che stai accedendo. In produzione, display_errors va disabilitato, ma nello sviluppo può essere attivato per vedere i dettagli (verifica in php.ini).

4. Controlla permessi su file e cartelle: Il server gira con un utente specifico e deve avere i permessi per leggere i file del sito e scrivere su cartelle di upload e log.

   macOS:

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

   L’utente server web (di solito _www) deve avere accesso in lettura (e in scrittura se carica file o scrive log). Usa chmod e chown per sistemare permessi e proprietà.

   Windows:

   dir C:\ServBay\www\your-site

   Su Windows, assicurati che l’account che esegue ServBay abbia i permessi necessari sulla directory. Modifica i permessi tramite le proprietà del file.

Diagnosi specifica per server web in caso di errore 500

• Caddy:

  1. Configurazione FastCGI: Verifica che le direttive php_fastcgi o reverse_proxy nel Caddyfile puntino al giusto indirizzo di PHP-FPM (127.0.0.1:9000 o unix:/path/to/php-fpm.sock).
  2. Stato PHP-FPM: Assicurati che la versione PHP corretta sia attiva in ServBay e che PHP-FPM sia funzionante.
  3. Proxy: Se usi reverse_proxy verso altri backend (es. Node.js), verifica indirizzo/porta e che il servizio di backend sia operativo.

• NGINX:

  1. Configurazione fastcgi_pass: Verifica nel file di configurazione che l’indirizzo FastCGI sia corretto.
  2. client_max_body_size: L’errore 500 su upload di file grandi può essere dovuto a un valore troppo basso.
  3. Direttiva try_files: Accertati che la direttiva sia ben configurata e che indirizzi correttamente le richieste agli indici o a FastCGI.

• Apache:

  1. Modulo mod_rewrite: Se usi .htaccess per il rewrite, assicurati che il modulo sia abilitato.
  2. Contenuto di .htaccess: Errori in .htaccess causano subito errori 500. Verifica la sintassi di direttive come RewriteRule.
  3. Impostazione AllowOverride: Controlla che la directory nel file di configurazione consenta l’override necessario per le direttive di .htaccess (tipicamente All, o almeno FileInfo e Limit).

Gestione dei servizi

Dopo aver modificato configurazioni o risolto problemi backend, è necessario riavviare il server web o i servizi correlati per rendere effettivi i cambiamenti.

Riavvio dei servizi

Usa il comando servbayctl restart per riavviare il servizio selezionato.

# Riavvia il servizio Caddy
servbayctl restart caddy -all

# Riavvia il servizio NGINX
servbayctl restart nginx -all

# Riavvia il servizio Apache
servbayctl restart apache -all

L’opzione -all riavvia anche i servizi collegati (es. PHP-FPM in caso di FastCGI).

Verifica dello stato dei servizi

Il comando servbayctl status mostra lo stato attuale del servizio.

# Verifica lo stato di Caddy
servbayctl status caddy -all

# Verifica lo stato di NGINX
servbayctl status nginx -all

# Verifica lo stato di Apache
servbayctl status apache -all

Il risultato indicherà se il servizio è running (attivo), stopped (fermo) o altri stati, per confermare l’avvio corretto.

Diagnosi avanzata

Se le procedure precedenti non risolvono, prova questi metodi di troubleshooting più avanzati:

1. Controlla DevTools del browser: Premi F12 e analizza tab Console e Network per errori JavaScript, codici di stato HTTP, headers e corpi delle risposte, per distinguere se il problema è frontend o backend.
2. Prova con curl -v: Da terminale, esegui curl -v your-website.servbay.demo (sostituisci con il tuo dominio reale ServBay) per vedere l’intero flusso della richiesta e della risposta a livello protocollo.
3. Disabilita temporaneamente il firewall: Il firewall locale di macOS o software di sicurezza possono bloccare le connessioni in ingresso. Prova a disabilitarlo per un test e, se il problema si risolve, configura regole che permettano il traffico sulle porte utilizzate da ServBay (80, 443, ecc.).
4. Prova su browser/dispositivo diversi: Accedi dal browser alternativo o da un altro computer per assicurarti che non si tratti di problemi di cache/cookie o di configurazioni locali.
5. Controlla la risoluzione DNS o il file hosts locale: Se usi domini personalizzati e non solo localhost o IP, verifica che i riferimenti puntino a 127.0.0.1 o ::1.
   • macOS: /etc/hosts
   • Windows: C:\Windows\System32\drivers\etc\hosts

Conclusione

I problemi ai server web sono una delle sfide più comuni nello sviluppo locale. Un approccio sistematico — verificando sintassi delle configurazioni, analizzando i log, controllando lo stato dei servizi e i permessi — aiuta a risolvere la maggior parte delle difficoltà. Gli strumenti integrati di ServBay, sia GUI sia CLI (servbayctl), rappresentano validi alleati. In caso di problematiche avanzate, consulta la documentazione dettagliata ServBay o chiedi assistenza al supporto tecnico.