Come installare Cachet su Debian 12 per una pagina stato

Cachet su Debian 12: scelta dello stack

Cachet è una web app PHP per una pagina stato. Su Debian 12 la strada più lineare è Nginx + PHP-FPM + MariaDB, perché riduce complessità e ti lascia un setup pulito per HTTPS, caching e manutenzione.

Assumo un server Debian 12 aggiornato, un dominio già puntato verso l’host e accesso root o sudo. Se stai mettendo la pagina stato in produzione, tratta il sistema come esposto a utenti esterni: aggiorna prima, installa poi, e tieni sempre un rollback semplice.

Requisiti minimi e prerequisiti operativi

Prima di installare, verifica questi punti:

• Debian 12 aggiornato
• Un FQDN, ad esempio status.example.com
• PHP compatibile con la versione di Cachet che vuoi usare
• Database MariaDB o MySQL
• Nginx come web server
• Certificato TLS valido, meglio con Let’s Encrypt

Se non hai ancora deciso la versione di Cachet, controlla il repository ufficiale del progetto e la compatibilità PHP richiesta. Questo è il primo punto dove non bisogna andare a intuito: la compatibilità tra release di Cachet e PHP cambia nel tempo.

Aggiornamento base del sistema

Parti da una base pulita. Su Debian 12 esegui gli aggiornamenti e installa i pacchetti necessari per il deployment.

sudo apt update
sudo apt upgrade -y
sudo apt install -y nginx mariadb-server git unzip curl ca-certificates \
php-fpm php-cli php-mysql php-xml php-curl php-mbstring php-zip php-bcmath php-intl php-gd \
composer redis-server

Se non vuoi Redis, puoi ometterlo, ma molte installazioni di app PHP moderne beneficiano di una coda o cache esterna. Per Cachet, dipende dalla release e dalla configurazione che scegli.

Verifica subito che i servizi base siano attivi:

systemctl status nginx mariadb php8.2-fpm

Atteso: active (running). Se la tua versione PHP differisce, sostituisci php8.2-fpm con il servizio effettivo rilevato da systemctl list-units 'php*-fpm.service'.

Creazione del database

Cachet ha bisogno di un database dedicato. Non usare l’account root del DB per l’applicazione.

sudo mysql

Dentro la shell MariaDB:

CREATE DATABASE cachet CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'cachetuser'@'localhost' IDENTIFIED BY 'PASSWORD_FORTE_E_RANDONDO';
GRANT ALL PRIVILEGES ON cachet.* TO 'cachetuser'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Il database deve essere utf8mb4, altrimenti ti esponi a problemi con caratteri speciali e contenuti futuri della pagina stato.

Verifica accesso e schema base con:

mysql -u cachetuser -p -h localhost -e 'SHOW DATABASES;'

Atteso: presenza di cachet.

Download dell’applicazione

Qui serve un punto fermo: usa il repository o la release ufficiale della versione Cachet che intendi distribuire. Le vecchie istruzioni basate su branch storici spesso non sono più corrette. Se il progetto ha una release stabile, preferisci quella. Se il repository richiede build o dipendenze specifiche, segui il README della release.

Schema tipico di deploy in produzione:

sudo mkdir -p /var/www/cachet
sudo chown -R $USER:$USER /var/www/cachet
cd /var/www/cachet
# Esempio: sostituisci con la sorgente ufficiale della tua versione
# git clone <repo-ufficiale> .

Se la versione prevede pacchetto sorgente o archivio compresso, scaricalo e decomprimilo nella directory di document root. L’obiettivo è avere i file applicativi in un path stabile, ad esempio /var/www/cachet.

Verifica la presenza di file di configurazione di esempio, file .env o istruzioni di installazione. Se la release usa Composer, installa dipendenze senza dev dependencies:

composer install --no-dev --optimize-autoloader

Se il comando fallisce, il problema più probabile è la versione PHP o una dipendenza mancante. In quel caso, non forzare: allinea prima la versione PHP richiesta dalla release.

Configurazione dell’ambiente applicativo

Molte installazioni Cachet moderne usano un file ambiente. Se la tua release lo prevede, crea o modifica .env con i parametri principali:

APP_ENV=production
APP_DEBUG=false
APP_URL=https://status.example.com
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=cachet
DB_USERNAME=cachetuser
DB_PASSWORD=PASSWORD_FORTE_E_RANDONDO

Non lasciare APP_DEBUG=true in produzione. Su una pagina stato pubblica, il debug esposto è un rischio inutile e può rivelare dettagli interni.

Se la release richiede permessi scrivibili su alcune directory, applicali in modo mirato, non con chmod 777. Tipicamente devono essere scrivibili le directory di cache, log o storage.

sudo chown -R www-data:www-data /var/www/cachet
sudo find /var/www/cachet -type d -exec chmod 755 {} \
;
sudo find /var/www/cachet -type f -exec chmod 644 {} \
;

Se esiste una directory storage specifica, concedi scrittura solo lì. Meglio ancora, usa gruppi e ACL se il progetto è articolato.

Configurazione di Nginx

Per una pagina stato, Nginx è una scelta solida. Crea un virtual host dedicato:

sudo nano /etc/nginx/sites-available/cachet.conf

Contenuto base:

server {
    listen 80;
    server_name status.example.com;
    root /var/www/cachet/public;
    index index.php index.html;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/run/php/php8.2-fpm.sock;
    }

    location ~* \.(css|js|png|jpg|jpeg|gif|ico|svg|webp)$ {
        expires 7d;
        access_log off;
    }

    location ~ /\.(?!well-known).* {
        deny all;
    }
}

Attiva il sito e ricarica Nginx:

sudo ln -s /etc/nginx/sites-available/cachet.conf /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Il test nginx -t deve restituire syntax is ok e test is successful. Se fallisce, non ricaricare il servizio.

Se il socket PHP-FPM non è quello indicato, ricavalo con:

ls /run/php/

e aggiorna fastcgi_pass di conseguenza.

HTTPS con Let’s Encrypt

Per una pagina stato pubblica, TLS è obbligatorio. Installa Certbot e genera il certificato:

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d status.example.com

Verifica il rinnovo automatico:

systemctl status certbot.timer
certbot renew --dry-run

Atteso: timer attivo e dry-run senza errori. Se usi un proxy o CDN davanti, controlla che la validazione HTTP-01 non venga bloccata.

Inizializzazione dell’applicazione

A questo punto va eseguito il bootstrap previsto dalla release. A seconda della versione, può essere un comando Artisan, una migrazione o una procedura web-based. Se la tua release usa Laravel o un framework analogo, il pattern tipico è:

cd /var/www/cachet
php artisan key:generate
php artisan migrate --force
php artisan config:cache
php artisan route:cache

Se uno di questi comandi non esiste, non insistere: significa che la release che stai usando ha un flusso diverso. In quel caso devi seguire il README ufficiale della versione installata.

Per l’installazione via interfaccia web, apri https://status.example.com e completa i campi richiesti: nome sito, mail amministrativa, parametri DB, eventuale SMTP. Se il wizard segnala errori di scrittura o connessione al DB, controlla prima permessi e credenziali.

SMTP e notifiche

Una pagina stato senza mail non è completa. Configura un relay SMTP affidabile, meglio se esterno al server che ospita Cachet. I parametri tipici da verificare sono host, porta, username, password, TLS e sender address.

Se la UI di Cachet prevede la configurazione mail, usa un indirizzo mittente coerente con il dominio della pagina stato. Per esempio status@example.com o no-reply@status.example.com.

Verifica il flusso con una notifica di test o con un evento di prova. Se le mail non partono, controlla i log applicativi e la coda. Su Debian, i log utili sono spesso:

• /var/log/nginx/error.log
• /var/log/nginx/access.log
• log PHP-FPM via journalctl -u php8.2-fpm
• log applicativi nella directory storage o logs della release

Queue, cron e task pianificati

Molte app PHP richiedono task periodici per email, aggiornamenti o pulizia cache. Se Cachet li prevede, imposta un cron dedicato per l’utente di servizio:

sudo crontab -u www-data -e

Esempio generico, da adattare alla tua release:

* * * * * cd /var/www/cachet && php artisan schedule:run >> /dev/null 2>&1

Se la tua versione usa queue worker, valuta un servizio systemd dedicato o Supervisor. Su Debian 12 systemd è spesso sufficiente, ma solo se la release documenta il comando da eseguire.

Controlla che i processi programmati siano vivi e senza errori:

systemctl list-timers
journalctl -u php8.2-fpm -n 50 --no-pager

Hardening minimo per produzione

Una pagina stato è pubblica, quindi il minimo sindacale è ridurre esposizione e aumentare robustezza.

• Disabilita il debug
• Tieni aggiornati Nginx, PHP e il framework
• Usa un account DB dedicato con privilegi limitati alla sola base cachet
• Proteggi i file di configurazione con permessi adeguati
• Espandi il firewall solo su 80/443 e SSH amministrativo
• Se possibile, metti backup giornalieri del DB e della configurazione

Se usi UFW:

sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status verbose

Atteso: solo SSH, HTTP e HTTPS aperti. Se il server espone altro, correggi prima di pubblicare.

Verifica finale del servizio

Prima di considerare l’installazione finita, fai queste verifiche pratiche:

1. curl -I https://status.example.com deve restituire 200 o 302 coerente con il wizard o la home della pagina stato
2. Il certificato deve risultare valido nel browser
3. Nginx deve essere active (running)
4. PHP-FPM deve essere active (running)
5. MariaDB deve essere active (running)
6. I log non devono mostrare errori di permessi, DB o PHP

Se vuoi un controllo rapido lato CLI:

curl -sS https://status.example.com | head

Atteso: HTML della pagina o del wizard, non errori 500 o pagine vuote.

Backup e rollback

Prima di mettere in produzione, salva almeno questi elementi:

• Dump del database: mysqldump cachet > cachet.sql
• Configurazione Nginx: /etc/nginx/sites-available/cachet.conf
• File ambiente o config applicativa
• Eventuali modifiche a cron o systemd

Rollback minimo se qualcosa va storto:

1. Disabilita il virtual host con il symlink in /etc/nginx/sites-enabled/
2. Ripristina il backup della config applicativa
3. Ricarica Nginx con nginx -t prima di reload
4. Se il DB è stato migrato male, ripristina il dump precedente

Assunzione: la release di Cachet usata richiede PHP-FPM, un database SQL e una document root pubblica in /public; se la versione che hai scelto differisce, allinea i comandi al README ufficiale della release.

Note pratiche per non perdere tempo in assistenza

Se la pagina non parte, i colpevoli più frequenti sono sempre gli stessi: socket PHP sbagliato, permessi errati sulla directory di storage, credenziali DB non valide, versione PHP incompatibile, o root documentale puntata al path sbagliato. Prima di rifare tutto, controlla questi cinque punti.

Se vuoi una configurazione più pulita in futuro, puoi separare database, reverse proxy e applicazione su host diversi. Ma per una pagina stato semplice, su Debian 12 un singolo nodo ben configurato è spesso sufficiente e più facile da mantenere.