BoxBilling su AlmaLinux 9 si installa senza troppi fronzoli, ma conviene farlo con ordine: prima prepari il runtime PHP compatibile, poi il database, quindi il virtual host e infine l’installer web. Il punto critico non è tanto “farlo partire”, quanto evitare gli errori tipici di PHP moderno, permessi sbagliati e dipendenze mancanti che saltano fuori solo al primo accesso alla pagina di setup.
In questa guida uso un approccio lineare, adatto a un server appena installato o a una macchina dove vuoi aggiungere BoxBilling senza toccare troppo il resto. Do per scontato AlmaLinux 9 con accesso root o sudo, dominio già puntato verso il server e una scelta chiara tra Apache e Nginx. Se un passaggio non è verificabile subito, lo segnalo con il controllo da fare: niente supposizioni, perché con questo tipo di pannelli il problema spesso emerge solo dopo il deploy.
Compatibilità reale: prima il PHP, poi BoxBilling
BoxBilling non è un’applicazione da installare “alla cieca” con l’ultimo PHP disponibile. Su AlmaLinux 9 il PHP di sistema può essere troppo recente per alcune versioni del progetto, quindi il primo controllo è capire quale release di BoxBilling stai usando e quale versione PHP richiede. Se la versione non è dichiarata chiaramente nella documentazione che hai in mano, fermati qui e verifica il file di requisiti o la pagina di release del progetto: è il punto che evita metà dei problemi a valle.
Per il resto della guida assumo un’installazione PHP-FPM con MariaDB e web server Apache o Nginx. Se usi un repository di terze parti per PHP, considera il rischio operativo: va bene per sbloccare la compatibilità, ma va tracciato e versionato, perché poi gli update del sistema non seguono più il ciclo standard di AlmaLinux.
Pacchetti base e repository necessari
Parti aggiornando il sistema e installando gli strumenti base. Questa fase è banale, ma utile per intercettare subito problemi di repository o conflitti tra moduli PHP.
sudo dnf -y update
sudo dnf -y install wget unzip tar policycoreutils-python-utils firewalldSe il PHP di AlmaLinux 9 non è compatibile con BoxBilling che vuoi usare, aggiungi il repository più adatto al tuo standard operativo. In molte installazioni si usa Remi per gestire versioni PHP specifiche. Il dettaglio importante è non mischiare pacchetti da sorgenti diverse senza criterio: scegli una linea e mantienila coerente su web server, CLI e PHP-FPM.
sudo dnf -y install epel-release
sudo dnf -y install https://rpms.remirepo.net/enterprise/remi-release-9.rpm
sudo dnf -y module reset phpIl reset del modulo PHP serve a evitare che il modulo di sistema interferisca con la versione che andrai a selezionare. Verifica subito lo stato dei moduli disponibili.
dnf module list phpSe non vedi la versione richiesta da BoxBilling, non andare avanti: prima risolvi la compatibilità del runtime, poi installa l’applicazione. Questo è il tipo di errore che costa meno correggere all’inizio che dopo aver già configurato database e virtual host.
Installare Apache o Nginx con PHP-FPM
BoxBilling lavora bene con entrambi, ma la combinazione più semplice da gestire in manutenzione è Apache con PHP-FPM oppure Nginx con PHP-FPM. Se vuoi una procedura lineare, Apache è spesso il percorso meno ambiguo; se hai già Nginx in standard, resta su quello. L’importante è non servire PHP come file statico per errore di configurazione.
Per Apache:
sudo dnf -y install httpd php php-fpm php-cli php-common php-mysqlnd php-gd php-mbstring php-xml php-curl php-zip php-opcache php-intl
sudo systemctl enable --now httpd php-fpmPer Nginx:
sudo dnf -y install nginx php php-fpm php-cli php-common php-mysqlnd php-gd php-mbstring php-xml php-curl php-zip php-opcache php-intl
sudo systemctl enable --now nginx php-fpmControlla subito che PHP-FPM stia rispondendo e che la versione sia quella attesa.
php -v
systemctl status php-fpm --no-pagerSe la versione non coincide con quella richiesta dalla tua release di BoxBilling, fermati e correggi qui. È più semplice cambiare il repository PHP adesso che scoprire più tardi errori fatali nelle pagine del pannello.
Preparare MariaDB per BoxBilling
BoxBilling usa un database relazionale standard, quindi MariaDB va benissimo. Installa il servizio, avvialo e crea un database dedicato con un utente separato. Non usare l’account root del database per l’applicazione: non serve e peggiora l’impatto di un eventuale leak di credenziali.
sudo dnf -y install mariadb-server
sudo systemctl enable --now mariadbVerifica che il servizio sia attivo prima di creare il database.
systemctl status mariadb --no-pagerOra crea database e utente. Sostituisci la password con una robusta e non riutilizzata altrove; se finisce in una shell history o in un file di provisioning, trattala come segreto da ruotare se c’è anche solo il dubbio di esposizione.
sudo mysql -u root -pCREATE DATABASE boxbilling CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'boxbillinguser'@'localhost' IDENTIFIED BY 'PASSWORD_FORTE_E_NON_RIUTILIZZATA';
GRANT ALL PRIVILEGES ON boxbilling.* TO 'boxbillinguser'@'localhost';
FLUSH PRIVILEGES;
EXIT;Il charset utf8mb4 evita sorprese con caratteri multibyte in descrizioni, note o campi inseriti dagli utenti. È una scelta semplice che ti risparmia migrazioni inutili dopo.
Scaricare BoxBilling e posizionarlo nel document root
Scarica l’archivio ufficiale della release che hai scelto e decomprimilo in una directory dedicata. Se hai un pacchetto .zip o .tar.gz, mantieni il contenuto pulito: niente annidamenti strani sotto il document root, perché poi gli URL e i path del pannello diventano meno prevedibili.
sudo mkdir -p /var/www/boxbilling
cd /tmp
wget -O boxbilling.zip https://example.com/boxbilling.zip
sudo unzip boxbilling.zip -d /var/www/boxbillingIl link di download è un segnaposto: usa il pacchetto ufficiale della release che stai adottando. Se il progetto distribuisce il codice in un repository Git, puoi usare anche quel canale, ma il principio non cambia: verifica integrità, versione e struttura dei file prima di esporre il sito.
Imposta i permessi in modo coerente con il web server. Su AlmaLinux è buona norma far sì che il contenuto sia leggibile dal servizio web e scrivibile solo dove serve davvero, per esempio cache, upload o directory runtime, se BoxBilling le usa.
sudo chown -R apache:apache /var/www/boxbilling
sudo find /var/www/boxbilling -type d -exec chmod 755 {} \;
sudo find /var/www/boxbilling -type f -exec chmod 644 {} \;Se usi Nginx con PHP-FPM, sostituisci il gruppo o l’utente in base al tuo modello operativo, ma resta prudente: non aprire scritture dove non servono. Se BoxBilling richiede directory specifiche scrivibili, limita i permessi a quelle sole directory dopo averle identificate nella documentazione o nei messaggi dell’installer.
Configurare il virtual host
Qui si gioca una parte importante della stabilità: document root corretto, gestione del front controller e passaggio delle richieste PHP a PHP-FPM. Se sbagli questo blocco, BoxBilling può caricarsi come pagina bianca, restituire 403 o mostrare errori di routing apparentemente casuali.
Per Apache, un virtual host minimo può essere questo:
<VirtualHost *:80>
ServerName billing.example.com
DocumentRoot /var/www/boxbilling
<Directory /var/www/boxbilling>
AllowOverride All
Require all granted
</Directory>
ErrorLog /var/log/httpd/boxbilling-error.log
CustomLog /var/log/httpd/boxbilling-access.log combined
</VirtualHost>Se BoxBilling usa `.htaccess` per la riscrittura, `AllowOverride All` deve restare attivo. Dopo aver salvato il file, verifica la sintassi e ricarica Apache.
sudo apachectl configtest
sudo systemctl reload httpdPer Nginx, la logica è simile ma la riscrittura va gestita nel server block. Un esempio essenziale:
server {
listen 80;
server_name billing.example.com;
root /var/www/boxbilling;
index index.php index.html;
location / {
try_files $uri $uri/ /index.php?$query_string;
}
location ~ \.php$ {
include fastcgi_params;
fastcgi_pass unix:/run/php-fpm/www.sock;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
}
}Con Nginx, dopo aver salvato il file, controlla la sintassi prima del reload. È un controllo banale ma evita downtime autoindotto.
sudo nginx -t
sudo systemctl reload nginxSELinux: il dettaglio che rompe installazioni altrimenti corrette
Su AlmaLinux 9 SELinux è normalmente attivo e, se lo lasci in modalità enforcing, fa il suo lavoro. Però devi dargli le etichette giuste per il document root e, se necessario, per le directory scrivibili dall’applicazione. Ignorarlo porta a errori strani: file presenti, permessi Unix corretti, ma accesso negato dal contesto SELinux.
Per il contenuto web standard, assegna il contesto corretto alla directory dell’applicazione.
sudo semanage fcontext -a -t httpd_sys_content_t "/var/www/boxbilling(/.*)?"
sudo restorecon -Rv /var/www/boxbillingSe BoxBilling deve scrivere in una directory specifica, ad esempio cache o upload, assegna a quella sola directory un contesto di scrittura adatto. Non allargare il permesso all’intero albero solo per comodità.
sudo semanage fcontext -a -t httpd_sys_rw_content_t "/var/www/boxbilling/cache(/.*)?"
sudo restorecon -Rv /var/www/boxbilling/cacheSe qualcosa non funziona, il controllo più rapido è guardare i log AVC.
sudo ausearch -m AVC -ts recentFirewall e HTTPS
Prima di esporre il pannello, apri solo le porte necessarie. Su un server web standard bastano HTTP e HTTPS. Se stai ancora testando in locale, puoi rimandare l’apertura di 443 finché non hai il certificato pronto, ma non lasciare il servizio in chiaro più del necessario.
sudo systemctl enable --now firewalld
sudo firewall-cmd --permanent --add-service=http
sudo firewall-cmd --permanent --add-service=https
sudo firewall-cmd --reloadPer il certificato, la via più semplice è Let’s Encrypt con Certbot. Il vantaggio non è solo il TLS: hai anche una configurazione ripetibile e una scadenza gestibile in modo automatico.
sudo dnf -y install certbot python3-certbot-apacheOppure, per Nginx:
sudo dnf -y install certbot python3-certbot-nginxPoi richiedi il certificato per il dominio reale. Il comando cambia in base al web server scelto.
sudo certbot --apache -d billing.example.comOppure:
sudo certbot --nginx -d billing.example.comSe il dominio non risolve ancora verso il server, Certbot fallisce: in quel caso chiudi il gap prima con un controllo DNS e poi riparti. Non forzare una configurazione TLS senza un nome host valido, perché l’errore è quasi sempre di contesto, non di certificato.
Avviare l’installer web di BoxBilling
A questo punto il sito deve rispondere almeno con la pagina iniziale o con l’installer. Apri il browser su `http://billing.example.com` oppure `https://billing.example.com` se hai già il certificato. Se ottieni una pagina bianca, il problema va quasi sempre cercato in PHP, nei permessi o in un errore fatale nascosto nei log.
Prima di cliccare qualsiasi cosa, fai un controllo sintetico da shell. È il modo più rapido per capire se il web server risponde e quale codice HTTP restituisce.
curl -I http://billing.example.comSe vedi `200`, `301` o `302`, il layer web è vivo. Se vedi `403`, `404`, `500` o timeout, il problema è più a monte e conviene leggere i log prima di continuare.
Durante l’installazione, BoxBilling ti chiederà i parametri del database e dati amministrativi iniziali. Inserisci il database creato prima, con l’utente dedicato. Se il form fallisce al salvataggio, la verifica successiva è semplice: guarda se il file di configurazione è stato scritto e se il web server ha permessi sulla directory prevista.
In questa fase il rischio tipico è una configurazione salvata ma non leggibile dal processo PHP, oppure un errore SQL legato a credenziali sbagliate o a un servizio MariaDB non raggiungibile. Non cambiare tre variabili insieme: controlla una ipotesi per volta.
Controlli di log quando qualcosa non torna
Se l’installazione si ferma, i log ti dicono più del browser. Parti dal web server e da PHP-FPM, poi scendi sul database. Su AlmaLinux i path possono variare in base alla tua configurazione, ma questi sono i punti da leggere per primi.
sudo tail -n 50 /var/log/httpd/error_log
sudo tail -n 50 /var/log/php-fpm/error.log
sudo journalctl -u php-fpm -n 50 --no-pager
sudo journalctl -u mariadb -n 50 --no-pagerCon Nginx, il file di errore dipende dal virtual host, ma la logica non cambia: cerca errori di fastcgi, permessi negati e path script non risolti. Se il database rifiuta la connessione, la pagina di setup può sembrare “bloccata” mentre in realtà aspetta una risposta che non arriva mai.
Un test utile è verificare direttamente la connessione al database con le stesse credenziali dell’applicazione.
mysql -u boxbillinguser -p -h localhost boxbillingSe questo comando entra senza errori, il problema non è il database in sé ma il modo in cui BoxBilling o PHP sta usando la connessione.
Hardening minimo dopo il primo avvio
Una volta completato il setup, conviene fare due cose subito: chiudere i permessi dove non servono e verificare che il pannello non esponga più del necessario. Se BoxBilling crea file di configurazione o directory scrivibili durante l’installazione, riduci la superficie appena hai finito.
Controlla i permessi del file di configurazione principale e delle directory runtime. Se un file contiene credenziali o dati sensibili, deve essere leggibile solo dal processo che ne ha bisogno. Se ti accorgi che un segreto è finito in chiaro in un file di provisioning o in una documentazione interna, ruotalo subito invece di lasciarlo lì “temporaneamente”.
Un audit minimo utile su un server di questo tipo è semplice: porte esposte, servizi attivi, aggiornamenti pendenti e log degli errori recenti. Non serve inventarsi un framework di compliance per sapere se l’installazione è sana.
sudo ss -tulpn
sudo systemctl --failed
sudo dnf check-updateSe vuoi automatizzare il controllo di salute, aggiungi una verifica HTTP al pannello e un controllo sul servizio PHP-FPM. Una semplice `curl -fsS` verso la home del sito ti dice subito se il front-end è vivo, mentre `systemctl is-active php-fpm` ti conferma che il backend non è caduto dopo l’installazione.
Schema operativo consigliato
Se vuoi una sequenza breve e ripetibile, il flusso corretto è questo: sistema aggiornato, repository PHP compatibile, web server e PHP-FPM, MariaDB, download di BoxBilling, virtual host, SELinux, firewall, TLS, installazione web, verifica log e hardening finale. Saltare l’ordine aumenta il tempo perso perché i sintomi si sovrappongono: un errore di permessi può sembrare un problema di database, e un problema di PHP può sembrare un bug dell’applicazione.
Il vantaggio di lavorare così è che ogni fase ha un controllo immediato: `php -v`, `systemctl status`, `curl -I`, log applicativi, `ausearch` per SELinux. Sono verifiche veloci, ma fanno la differenza quando devi chiudere un’installazione in modo pulito e non “a tentativi”.
Se la tua versione di BoxBilling richiede estensioni PHP aggiuntive, aggiungile solo dopo aver confermato l’errore reale nei log. Il rischio opposto è installare moduli inutili e confondere il troubleshooting. La regola pratica resta la stessa: prima osserva, poi modifica, poi verifica di nuovo.
Con AlmaLinux 9, BoxBilling si installa bene quando il runtime è scelto con criterio e il web server è configurato senza scorciatoie. Il resto è disciplina operativa: permessi stretti, segreti gestiti bene, log letti davvero e rollback possibile se una modifica rompe il servizio.
Commenti (0)
Nessun commento ancora.
Segnala contenuto
Elimina commento
Eliminare definitivamente questo commento?
L'azione non si può annullare.