Struttura delle Directory di ServBay – Guida Completa

Panoramica

ServBay è un ambiente di sviluppo web locale compatibile con macOS e Windows, con una struttura delle directory progettata per essere ordinata e intuitiva. Se hai familiarità con i sistemi Linux/Unix, troverai la disposizione dei file di ServBay simile agli standard di questi sistemi, facilitando la localizzazione e la gestione dei vari file necessari allo sviluppo.

Posizione di Installazione di ServBay

Posizioni di installazione predefinite di ServBay sui vari sistemi:

• macOS: /Applications/ServBay
• Windows: C:\ServBay

Comprendere la struttura delle directory di ServBay è fondamentale per uno sviluppo locale efficiente, per la configurazione, la risoluzione dei problemi e per il backup dei dati. In questa guida vengono illustrati in dettaglio le directory principali e la loro funzione.

Una tipica struttura di directory dopo l’installazione di ServBay appare così:

ServBay
|____backup                 # Directory dei backup
| |____config               # Backup delle configurazioni
| |____databases            # Backup dei database
| |____ssl                  # Backup certificati SSL
| |____websites             # Backup dei file dei siti web
|____bin                    # File eseguibili utente (collegamento a package/bin)
|____data                   # Dati interni di ServBay
| |____servbay              # Configurazione e dati core di ServBay
|____db                     # Directory dei file di database
| |____mariadb              # File database MariaDB
| |____mongodb              # File database MongoDB
| |____mysql                # File database MySQL
| |____postgresql           # File database PostgreSQL
| |____redis                # File database Redis
|____etc                    # Directory dei file di configurazione (collegamento a package/etc)
|____logs                   # Directory dei file di log (collegamento a package/var/log)
|____package                # Directory pacchetti software
| |____bin                  # Eseguibili dei pacchetti
| |____common               # Librerie condivise e librerie di sviluppo
| | |____imap-uw
| | |____include            # File header (ServBay Development Library)
| | |____lib                # Librerie condivise e statiche (ServBay Development Library)
| | |____libexec
| | |____openssl
| | |____share
| |____etc                  # Posizione reale configurazioni pacchetti
| | |____caddy
| | |____dnsmasq
| | |____mariadb
| | |____mongodb
| | |____mysql
| | |____nginx
| | |____openldap
| | |____php
| | |____postgresql
| | |____redis
| | |____... (configurazioni di altri pacchetti come Python, Go, Java, Ruby, Rust, ecc.)
| |____<package_name>       # Directory principale di ciascun pacchetto
| | |____<major_version>   # Directory della versione principale
| | | |____<full_version> # Directory della versione completa (include il pacchetto)
| | | |____current         # Collegamento alla versione più recente
| | |____...
| |____sbin                 # Eseguibili di sistema dei pacchetti
| |____var                  # Dati variabili dei pacchetti (come la posizione reale dei log)
| | |____log                # Log effettivi
| | |____run                # File di runtime (.pid, etc.)
|____sbin                   # Eseguibili di sistema (collegamento a package/sbin)
|____script                 # Script di gestione interni ServBay
|____ssl                    # Directory certificati SSL
| |____acme                 # Certificati SSL richiesti via ACME
| |____caddy                # Certificati SSL generati automaticamente da Caddy
| |____import               # Certificati SSL di terze parti importati
| |____private              # ServBay User CA
| |____public               # ServBay Public CA
|____tmp                    # Directory file temporanei e socket
|____www                    # Root dei siti web
| |____servbay              # Directory siti di esempio

Segue la spiegazione dettagliata delle varie directory.

Directory Principale di ServBay

La directory principale di ServBay si trova, di default, su /Applications/ServBay. Tutti i pacchetti software, file di configurazione, dati, log e altri file correlati sono centralizzati qui.

Per proteggere l’ambiente di sviluppo locale e la sicurezza dei dati, è consigliato eseguire backup regolari di questa directory principale. Puoi utilizzare Time Machine o altri software di backup per salvare l’intero percorso /Applications/ServBay.

Root dei Siti Web (www)

La directory principale dei file dei siti web è /Applications/ServBay/www. Qui vengono collocati tutti i progetti web locali.

Per una struttura ordinata e facilmente gestibile, si raccomanda vivamente di creare una sottocartella separata per ogni singolo progetto web o sito virtuale (definiti come “siti” in ServBay).

Ad esempio, se crei i siti web.servbay.demo, api.servbay.demo e new.servbay.local, la struttura consigliata sarebbe:

/Applications/ServBay/www
|____servbay.demo           # Tutti i siti con dominio *.servbay.demo
| |____web               # File di web.servbay.demo
| |____api               # File di api.servbay.demo
|____servbay.local          # Tutti i siti con dominio *.servbay.local
| |____new               # File di new.servbay.local
|____myproject              # Altri progetti indipendenti, es. myproject.local

Questa divisione aiuta a distinguere chiaramente i progetti, rendendo la gestione più semplice.

Directory dei File di Configurazione (etc)

La directory dei file di configurazione /Applications/ServBay/etc è, in realtà, un collegamento a /Applications/ServBay/package/etc. Qui risiedono le principali configurazioni di tutti i pacchetti installati (PHP, MariaDB, Nginx, Caddy, ecc.).

Durante l’utilizzo quotidiano puoi accedere e modificare direttamente i file di configurazione tramite /Applications/ServBay/etc. Di solito, dopo aver modificato questi file, è necessario riavviare il servizio corrispondente affinché le modifiche abbiano effetto.

Di seguito sono riportati esempi di organizzazione delle configurazioni dei pacchetti principali.

PHP (etc/php)

La directory di configurazione di PHP segue una struttura a due livelli, separando le diverse versioni principali di PHP. Troverai, sotto etc/php, le directory 5.6, 7.4, 8.3 e così via, ciascuna corrispondente a una versione principale di PHP. Esempio:

php
|____5.6                    # Configurazione PHP 5.6
| |____conf.d               # Directory per file di configurazione estensioni
| |____php.ini              # File di configurazione principale PHP
|____7.4                    # Configurazione PHP 7.4
| |____conf.d               # Configurazione estensioni
| |____php-fpm.d            # Configurazione pool PHP-FPM
| |____php-fpm.conf         # File principale PHP-FPM
| |____php.ini              # File principale PHP
|____8.3                    # Configurazione PHP 8.3
| |____conf.d
| |____php-fpm.d
| |____php-fpm.conf
| |____php.ini
|____... (altre versioni PHP)

Ogni directory di versione include php.ini (configurazione principale PHP), php-fpm.conf (configurazione principale FPM, se supportato), file come pear.conf e simili. Dopo ogni modifica è opportuno riavviare il servizio PHP-FPM tramite il pannello ServBay o usando il comando servbayctl.

La cartella conf.d contiene configurazioni delle estensioni PHP come xdebug.ini, opcache.ini, redis.ini. Modificando questi file puoi gestire le estensioni. Anche in questo caso, è necessario riavviare il servizio PHP-FPM.

Nota: In ServBay, tutte le versioni minori di PHP appartenenti alla stessa versione principale condividono la configurazione. Ad esempio, sia PHP 8.3.3 che 8.3.5 usano i file in etc/php/8.3.

MariaDB / MySQL / PostgreSQL (etc/mariadb, etc/mysql, etc/postgresql)

Le directory di configurazione dei database sono strutturate per versione, ad esempio etc/mariadb/11.2. Qui si trovano i file principali di configurazione (my.cnf per MariaDB/MySQL, postgresql.conf per PostgreSQL). Dopo modifiche a questi file, è necessario riavviare il servizio database. Anche qui, versioni minori di una versione maggiore condividono la configurazione.

Per resettare la password dell’utente root di MariaDB, MySQL o PostgreSQL si usano tool specifici o le funzioni del pannello ServBay, piuttosto che modificare i file direttamente.

Caddy (etc/caddy)

Il file di configurazione di Caddy, ossia il Caddyfile, si trova in etc/caddy.

Avviso Importante: ServBay genera il Caddyfile automaticamente in base alla configurazione dei “siti” impostata tramite il pannello di controllo. Non modificare direttamente questo file, perché le modifiche verranno sovrascritte al prossimo aggiornamento della configurazione. Per opzioni avanzate di Caddy per un sito, usa direttamente le impostazioni nel pannello ServBay.

Nginx (etc/nginx)

Il file principale di configurazione di Nginx (nginx.conf) si trova in etc/nginx. ServBay genera e include automaticamente le configurazioni dei siti. Modifiche manuali devono essere gestite con attenzione; si raccomanda di usare gli strumenti forniti dal pannello ServBay.

dnsmasq (etc/dnsmasq)

La configurazione di dnsmasq include dnsmasq.conf (configurazione predefinita) e domains.conf (generato da ServBay in base ai domini locali configurati).

Avviso Importante: Entrambi i file sono gestiti interamente da ServBay per garantire il corretto funzionamento della risoluzione dei domini. Non apportare modifiche manuali; eventuali cambiamenti potrebbero causare problemi di accesso ai siti locali.

Configurazioni di Altri Pacchetti

Per altri pacchetti supportati (Node.js, Python, Go, Java, Ruby, Rust, ecc.), eventuali file di configurazione globali sono di norma posizionati in una sottocartella dedicata nella directory etc, sempre strutturata per versione.

Directory Dati Interni di ServBay (data/servbay)

/Applications/ServBay/data/servbay

Questa directory contiene i file di configurazione essenziali, informazioni di stato e impostazioni utente per il funzionamento del core di ServBay. Questi file sono fondamentali per il pannello di controllo, la gestione dei pacchetti, la configurazione dei siti e dei database.

Avviso Importante: È cruciale eseguire backup regolari di questa directory. Non eliminare o modificare i file manualmente, altrimenti ServBay potrebbe non avviarsi o perdere la configurazione.

Directory Eseguibili e Script (bin, sbin, script)

/Applications/ServBay/bin -> package/bin
/Applications/ServBay/sbin -> package/sbin
/Applications/ServBay/script

Tutti i file eseguibili si trovano in bin e sbin, che puntano rispettivamente a package/bin e package/sbin. Da qui puoi accedere a strumenti e runtime linguaggi forniti da ServBay.

Questi percorsi vengono aggiunti automaticamente alla variabile PATH del sistema quando ServBay è attivo, quindi puoi avviare gli strumenti direttamente dal terminale, tra cui:

• Strumenti comuni: curl, openssl, frpc, ecc.
• Runtime linguaggi per diverse versioni: php (default), php-5.6, php-7.4, php-8.3, node (default), node-16, node-18, python3, go, java, ruby, rustc, ecc. Puoi richiamare versioni specifiche tramite comandi con il numero versione.
• Client database: mysql, psql, mongosh, redis-cli, ecc.

La directory script (/Applications/ServBay/script) include script di gestione interna, ad esempio per avviare/arrestare servizi, inizializzare database o svolgere operazioni di manutenzione. Normalmente è preferibile gestire tutto tramite il comando servbayctl, che incapsula questi script in una interfaccia più sicura.

Per avviare, ad esempio, PHP 7.4 FPM:

servbayctl start php 7.4

Il comando servbayctl è disponibile in /Applications/ServBay/bin.

Directory dei File di Database (db)

/Applications/ServBay/db

Questa directory contiene i file effettivi dei database installati tramite ServBay, organizzati per tipo di software e versione:

• /Applications/ServBay/db/mariadb/<major_version>: file di MariaDB
• /Applications/ServBay/db/mysql/<major_version>: file di MySQL
• /Applications/ServBay/db/postgresql/<major_version>: file di PostgreSQL
• /Applications/ServBay/db/mongodb: file di MongoDB
• /Applications/ServBay/db/redis: file di Redis

In ServBay, tutti i database di una stessa versione principale condividono i file all’interno della relativa cartella. Ad esempio, tutte le versioni della serie MariaDB 11.2.x utilizzano la directory /Applications/ServBay/db/mariadb/11.2.

Avviso Importante: Qui sono conservati tutti i dati dei database locali. Prima di upgrade, migrazioni o altre operazioni importanti, aggiungi questa directory (/Applications/ServBay/db) al tuo backup. Anche la funzione di backup automatico di ServBay salva i dati dei database.

Directory dei Log (logs)

/Applications/ServBay/logs -> package/var/log

Tutti i log dei servizi integrati sono raccolti in /Applications/ServBay/logs, che punta a /Applications/ServBay/package/var/log. In questo modo puoi consultare facilmente lo stato dei servizi e diagnosticare errori.

I file di log sono organizzati per servizio, tipicamente in sottocartelle come:

• logs/caddy/ o logs/nginx/: log degli accessi e degli errori, organizzati per dominio.
• logs/php/: log di PHP-FPM (php-fpm.log) ed errori PHP (errors.log), dove quest’ultimo raccoglie errori fatali non intercettati dalle applicazioni PHP.
• logs/mariadb/, logs/mysql/, logs/postgresql/, logs/mongodb/, logs/redis/: errori dei database, log di query lente, ecc.
• Altri log servizi: Python, Go, Java, Ruby, Rust e rispettivi log nelle proprie cartelle.

Nota: Gli accessi e i log degli errori possono occupare molto spazio, specialmente con progetti attivi. Si raccomanda di monitorare e pulire periodicamente questi file.

Directory dei Pacchetti Software (package)

/Applications/ServBay/package

Questa è la posizione reale dei software installati e gestiti tramite ServBay. Ogni pacchetto ha una propria sottocartella (nome_pacchetto/versione_grande/versione_completa). Ad esempio, una specifica versione di PHP sarà installata in /Applications/ServBay/package/php/8.3/8.3.7.

Tramite il pannello di ServBay è possibile installare, disinstallare e switchare tra diverse versioni di ogni pacchetto.

Per liberare spazio, puoi eliminare manualmente le directory delle versioni obsolete che non ti servono più (esempio: /Applications/ServBay/package/php/8.2/8.2.10).

Avviso Importante: Nella directory di ciascuna versione grande (/Applications/ServBay/package/php/8.3) esiste il collegamento current, che punta alla versione attiva. Non eliminare o modificare questi link, altrimenti ServBay potrebbe non trovare i file necessari per avviare i servizi.

Directory dei Certificati SSL (ssl)

/Applications/ServBay/ssl

Qui sono raccolti i file dei certificati SSL/TLS. Sono inclusi:

• Certificati SSL richiesti automaticamente tramite ACME per i siti locali, solitamente in ssl/caddy o ssl/acme, secondo il web server usato.
• CA e certificati pubblici generati da ServBay per l’HTTPS locale, presenti in ssl/private (ServBay User CA) e ssl/public (ServBay Public CA). Installando queste CA nel sistema, i certificati ServBay sono riconosciuti e non viene mostrato il warning HTTPS nel browser.

Directory dei Backup (backup)

/Applications/ServBay/backup

Questa directory raccoglie tutti i file di backup creati automaticamente da ServBay, inclusi:

• backup/config: backup delle configurazioni principali e dei pacchetti.
• backup/databases: backup dei dati di MariaDB, MySQL, PostgreSQL, MongoDB.
• backup/ssl: backup dei certificati SSL.
• backup/websites: backup dei progetti web nella directory www.

Controlla periodicamente questa directory e valuta di trasferire i backup importanti su dispositivi di archiviazione esterni per una protezione ottimale.

Directory dei File Temporanei (tmp)

/Applications/ServBay/tmp

Qui vengono creati file temporanei e socket dai vari servizi, tra cui:

• File .pid: contengono l’ID del processo attivo del servizio.
• File socket: come php-cgi.sock, mysql.sock, pgsql.sock, utilizzati per la comunicazione locale tra servizi (interprocesso). Rispetto alla comunicazione via TCP, i socket offrono prestazioni più elevate e minore latenza per lo sviluppo su macchina locale.

Componenti Condivisi e Librerie di Sviluppo (package/common)

/Applications/ServBay/package/common

Qui sono presenti le librerie condivise e i componenti di supporto necessari per tutti i pacchetti di ServBay.

Se installi la ServBay Development Library, qui troverai anche le directory include (file header) e lib (librerie statiche e di collegamento, come *.a, *.la). Questi file sono utili se devi compilare estensioni PHP o altri software personalizzati.

Avviso Importante: Non cancellare manualmente i file *.dylib nella directory package/common/lib, perché sono essenziali per il corretto funzionamento delle applicazioni integrate. L’eliminazione potrebbe causare errori dovuti a librerie mancanti.

Conclusioni

La struttura delle directory di ServBay suddivide chiaramente pacchetti, configurazioni, dati, log e file dei siti, nel rispetto delle convenzioni dei file system Unix, semplificando la gestione dell’ambiente di sviluppo locale. Familiarizzare con queste directory migliora significativamente efficienza e praticità nello sviluppo web con ServBay. Non dimenticare di eseguire regolarmente backup delle cartelle cruciali (data e db) per evitare la perdita accidentale dei tuoi dati di sviluppo.