Guida Completa alla Struttura delle Directory di ServBay

ServBay è un ambiente di sviluppo Web locale progettato specificamente per macOS, con una struttura delle directory ordinata e intuitiva. Se hai familiarità con i sistemi Linux/Unix, noterai molte somiglianze con le convenzioni standard di organizzazione dei file, facilitando così la gestione e il reperimento rapido dei vari componenti.

Comprendere la struttura delle directory di ServBay è essenziale per uno sviluppo locale efficiente, per configurare l’ambiente, risolvere problemi e pianificare i backup. In questo articolo analizziamo in dettaglio le principali directory di ServBay e il loro utilizzo.

Ecco un esempio tipico della struttura delle directory di un’installazione di ServBay:

ServBay
|____backup                 # Directory per i file di backup
| |____config               # Backup delle configurazioni
| |____databases            # Backup dei database
| |____ssl                  # Backup dei 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 di archiviazione dei file di database
| |____mariadb              # File di dati MariaDB
| |____mongodb              # File di dati MongoDB
| |____mysql                # File di dati MySQL
| |____postgresql           # File di dati PostgreSQL
| |____redis                # File di dati Redis
|____etc                    # Directory dei file di configurazione (symlink a package/etc)
|____logs                   # Directory dei file di log (symlink a package/var/log)
|____package                # Directory di installazione dei pacchetti
| |____bin                  # Eseguibili dei pacchetti
| |____common               # Librerie comuni e di sviluppo
| | |____imap-uw
| | |____include            # File header (Libreria di sviluppo ServBay)
| | |____lib                # Librerie condivise e statiche (Libreria di sviluppo ServBay)
| | |____libexec
| | |____openssl
| | |____share
| |____etc                  # Path reale delle configurazioni dei pacchetti
| | |____caddy
| | |____dnsmasq
| | |____mariadb
| | |____mongodb
| | |____mysql
| | |____nginx
| | |____openldap
| | |____php
| | |____postgresql
| | |____redis
| | |____... (config 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 (contiene il software)
| | | |____current          # Symlink alla versione completa più recente
| | |____...
| |____sbin                 # Eseguibili di sistema dei pacchetti
| |____var                  # Dati variabili dei pacchetti (posizione reale dei log ecc.)
| | |____log                # Log effettivi dei pacchetti
| | |____run                # File runtime (come file .pid)
|____sbin                   # Eseguibili di sistema (symlink a package/sbin)
|____script                 # Script di gestione interni ServBay
|____ssl                    # Directory dei certificati SSL
| |____acme                 # Certificati SSL ottenuti tramite protocollo ACME
| |____caddy                # Certificati SSL generati automaticamente da Caddy
| |____import               # Certificati SSL di terze parti importati
| |____private              # Root CA utilizzata da ServBay
| |____public               # Public CA di ServBay
|____tmp                    # File temporanei e socket
|____www                    # Directory root dei siti web
| |____servbay              # Siti di esempio

Segue la descrizione dettagliata di ciascuna directory.

Directory Principale di ServBay

La directory principale di ServBay si trova di default in /Applications/ServBay. Tutti i pacchetti, i file di configurazione, i dati e i log relativi a ServBay sono concentrati qui.

Per proteggere il tuo ambiente di sviluppo locale e i dati, si consiglia di eseguire regolari backup di questa directory principale. Puoi utilizzare Time Machine o altri strumenti di backup per eseguire una copia integrale di /Applications/ServBay.

Root dei Siti Web (www)

La cartella principale dei file dei siti web è /Applications/ServBay/www, il luogo dove inserire tutti i progetti Web locali.

Per mantenere una struttura ordinata e facilitare la gestione, si consiglia vivamente di creare una sottocartella per ciascun sito/progetto indipendente o per ciascun sito virtuale (in ServBay chiamati “siti”) all’interno di questa directory.

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

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

Questa organizzazione aiuta a distinguere chiaramente tra diversi progetti e domini, rendendo la gestione molto più semplice.

Directory dei File di Configurazione (etc)

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

Durante il normale utilizzo, puoi accedere e modificare i file di configurazione tramite il percorso /Applications/ServBay/etc. Dopo la modifica, è spesso necessario riavviare il relativo servizio per applicare i cambiamenti.

Ecco dove trovare le configurazioni per i pacchetti principali:

PHP (etc/php)

La directory delle configurazioni PHP segue una struttura a due livelli, distinguendo tra le versioni principali di PHP. Ad esempio, sotto etc/php troverai le directory 5.6, 7.4, 8.3, ecc., ciascuna per una major release. Struttura tipica:

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

Ogni directory contiene php.ini (configurazione principale), php-fpm.conf (configurazione PHP-FPM, se supportata), pear.conf e altro. Dopo ogni modifica, riavvia il relativo servizio PHP-FPM tramite il pannello di controllo ServBay o il comando servbayctl per applicare le impostazioni.

La cartella conf.d contiene file di configurazione delle estensioni PHP come xdebug.ini, opcache.ini, redis.ini ecc. Modificandoli puoi attivare, disattivare o configurare le estensioni. Anche in questo caso, è necessario riavviare PHP-FPM dopo ogni modifica.

Nota: ServBay usa lo stesso set di configurazione per tutte le minor version della stessa major version di PHP (es. 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)

Anche le configurazioni dei database sono organizzate per versione, ad esempio etc/mariadb/11.2. Qui troverai file come my.cnf per MariaDB/MySQL e postgresql.conf per PostgreSQL. Dopo una modifica, è necessario riavviare il servizio corrispondente. Come per PHP, tutte le minor version di una stessa major version condividono la stessa configurazione.

Il reset della password dell’utente root di MariaDB, MySQL o PostgreSQL non avviene modificando i file di configurazione, ma tramite tool a riga di comando o funzionalità dedicate nel pannello ServBay.

Caddy (etc/caddy)

Il file di configurazione di Caddy (Caddyfile) si trova in etc/caddy.

Attenzione: ServBay genera automaticamente il Caddyfile in base alle impostazioni dei siti definite nel pannello di controllo. Non modificarlo manualmente, poiché ogni rigenerazione sovrascriverà eventuali cambiamenti manuali. Per configurare opzioni avanzate per un sito, usa la sezione dedicata nella configurazione del sito tramite il pannello ServBay.

Nginx (etc/nginx)

La configurazione principale di Nginx (nginx.conf) si trova in etc/nginx. Anche questa può essere sovrascritta da ServBay in funzione della configurazione dei siti. Modificala con attenzione: è sempre preferibile modificare le configurazioni tramite il pannello di ServBay.

dnsmasq (etc/dnsmasq)

La directory contiene dnsmasq.conf (config default) e domains.conf (generato automaticamente da ServBay in base ai domini locali impostati).

Attenzione: Entrambi i file sono gestiti e generati da ServBay per garantire che la risoluzione dei domini locali funzioni correttamente. Non modificarli manualmente per non compromettere l’accesso ai siti locali.

Altre configurazioni dei pacchetti

I pacchetti supportati da ServBay come Node.js, Python, Go, Java, Ruby, Rust, ecc., se dispongono di file di configurazione a livello globale o di servizio, li archivieranno nelle rispettive sottodirectory di etc, seguendo la medesima struttura per versione.

Data Directory Interna di ServBay (data/servbay)

/Applications/ServBay/data/servbay

Questa directory ospita file di configurazione essenziali, informazioni sullo stato e impostazioni personalizzate per il funzionamento di ServBay. È fondamentale per la gestione tramite pannello di controllo, la gestione dei pacchetti, la configurazione dei siti e dei database.

Nota critica: Effettua regolari backup di questa directory e non eliminare o modificare manualmente alcun file: ciò potrebbe impedire a ServBay di avviarsi o portare alla perdita della configurazione.

Directory degli Eseguibili e Script (bin, sbin, script)

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

Tutti gli eseguibili di ServBay sono organizzati nelle directory bin e sbin, che sono collegamenti simbolici a package/bin e package/sbin. Qui si trovano tutti gli strumenti integrati e i runtime dei linguaggi.

La directory degli eseguibili viene automaticamente aggiunta al PATH del sistema (generalmente durante l’avvio di ServBay), così puoi richiamarli direttamente da terminale:

• Strumenti comuni: curl, openssl, frpc, ecc.
• Runtime multipli: php (versione predefinita), php-5.6, php-7.4, php-8.3, node (predefinito), node-16, node-18, python3, go, java, ruby, rustc, ecc. Puoi scegliere la versione specifica indicando il comando col numero di versione.
• Client database: mysql, psql, mongosh, redis-cli, ecc.

La directory script (/Applications/ServBay/script) contiene script gestione interna di ServBay per l’avvio/arresto dei servizi, l’inizializzazione e la manutenzione. Sebbene sia possibile eseguirli manualmente, è sempre preferibile utilizzare il comando servbayctl, che offre un’interfaccia più intuitiva e sicura.

Ad esempio, per avviare PHP 7.4 FPM:

servbayctl start php 7.4

Il tool servbayctl si trova in /Applications/ServBay/bin.

Directory dei File di Database (db)

/Applications/ServBay/db

Questa directory ospita i dati effettivi di tutti i database installati da ServBay. La struttura riflette l’organizzazione per pacchetto e per versione, ad esempio:

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

Per ogni database, le versioni principali condividono la stessa directory dati (tutti i rilasci della serie MariaDB 11.2.x usano /Applications/ServBay/db/mariadb/11.2).

Avviso: questa cartella contiene tutti i database locali. Effettua sempre un backup completo di /Applications/ServBay/db prima di operazioni importanti come upgrade di ServBay o migrazione del sistema. Il backup automatico di ServBay includerà anche questi dati.

Directory dei Log (logs)

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

Tutti i log dei servizi integrati vengono raccolti in /Applications/ServBay/logs, che è un symlink verso /Applications/ServBay/package/var/log. Qui puoi comodamente monitorare lo stato dei servizi e eventuali errori.

I log sono organizzati per servizio sottocartelle dedicate, ad esempio:

• logs/caddy/ o logs/nginx/: log di accesso ed errore di Caddy e Nginx, suddivisi per dominio.
• logs/php/: log di PHP-FPM (php-fpm.log) e log errori PHP (errors.log). Quest’ultimo archivia gli errori fatali non gestiti dalle applicazioni PHP.
• logs/mariadb/, logs/mysql/, logs/postgresql/, logs/mongodb/, logs/redis/: errori e query lente dei database.
• Altri log: anche Python, Go, Java, Ruby, Rust avranno una sottocartella dedicata se generano log.

Nota: I file di log, specialmente quelli di accesso e di errore, possono crescere molto rapidamente. Ti consigliamo di controllare e pulire regolarmente le directory log per risparmiare spazio su disco.

Directory dei Pacchetti (package)

/Applications/ServBay/package

Qui vengono installati e gestiti tutti i pacchetti di ServBay. Ogni pacchetto è organizzato in una struttura nome/major_version/full_version. Ad esempio, PHP 8.3.7 potresti trovarlo in /Applications/ServBay/package/php/8.3/8.3.7.

Nel pannello di controllo puoi installare, disinstallare e passare da una versione all’altra facilmente.

Per liberare spazio, puoi cancellare a mano le directory delle versioni obsolete (/Applications/ServBay/package/php/8.2/8.2.10).

Nota importante: In ogni directory di major version (es. /Applications/ServBay/package/php/8.3) c’è un link simbolico current che punta alla versione attualmente in uso. Non eliminarlo o modificarlo manualmente, pena il malfunzionamento di ServBay nel localizzare eseguibili e librerie e nell’avvio dei servizi.

Directory dei Certificati SSL (ssl)

/Applications/ServBay/ssl

Usata per archiviare tutti i certificati SSL/TLS:

• Certificati generati automaticamente con protocollo ACME per i siti locali (in ssl/caddy o ssl/acme a seconda del web server).
• Root CA e certificati pubblici per HTTPS locale (directory ssl/private e ssl/public). Installando questi CA sul sistema eviti avvisi di sicurezza nei browser per i siti serviti da ServBay.

Directory dei Backup (backup)

/Applications/ServBay/backup

Contiene i backup realizzati dal sistema integrato di ServBay. È possibile includere facilmente:

• backup/config: backup delle configurazioni core di ServBay e dei pacchetti.
• backup/databases: backup dei database (MariaDB, MySQL, PostgreSQL, MongoDB...).
• backup/ssl: backup dei certificati SSL.
• backup/websites: backup dei tuoi siti in /Applications/ServBay/www.

Consigliamo di verificare regolarmente questa directory e, se necessario, spostare i backup su supporti esterni come misura aggiuntiva di sicurezza.

Directory dei File Temporanei (tmp)

/Applications/ServBay/tmp

Qui vengono archiviati i file temporanei generati dai servizi, principalmente:

• File .pid: identificatori di processo dei servizi in esecuzione.
• Socket file: per esempio php-cgi.sock, mysql.sock, pgsql.sock, ecc. Consentono la comunicazione locale fra processi attraverso Unix Domain Socket, soluzione generalmente più performante e a minore latenza rispetto a una comunicazione via TCP/IP.

Componenti Comuni e Librerie di Sviluppo (package/common)

/Applications/ServBay/package/common

Raccoglie componenti condivisi e librerie dipendenti da tutti i pacchetti ServBay, tra cui file delle librerie condivise (*.dylib) ed eventuali librerie per lo sviluppo.

Installando la ServBay Development Library (pacchetto opzionale per le dipendenze di compilazione), qui troverai anche la directory include (header file) e lib (statiche .a e collegamenti .la). Questi file sono utili se vuoi compilare estensioni PHP dal sorgente o altri software che si appoggiano alle librerie interne di ServBay.

Avviso: Non eliminare i file .dylib in package/common/lib: sono necessari per il corretto funzionamento dei componenti ServBay e la loro assenza può causare errori di esecuzione.

Conclusione

La struttura delle directory di ServBay si ispira agli standard Unix, separando chiaramente pacchetti, configurazione, dati, log e siti web. Ciò ti consente una gestione intuitiva ed efficace dell’ambiente di sviluppo locale. Conoscere le funzioni di ciascuna directory ti aiuterà a lavorare con ServBay in modo ancora più produttivo. Ricorda di effettuare regolarmente backup ai dati critici (data, db) per proteggere il tuo lavoro di sviluppo.