Self-hosting

Questa guida copre la distribuzione in produzione di Gäld sul proprio server. Per lo sviluppo locale, consulta Per iniziare.

Requisiti del server

Componente	Versione minima
PHP	8.2
PostgreSQL	15
Redis	7
Nginx (o Caddy)	—
Node.js (solo build)	20

Un VPS con 2 vCPU, 2 GB di RAM e 20 GB SSD è sufficiente per la maggior parte delle piccole organizzazioni.

Installazione

git clone https://github.com/Scanix/Gaeld.git /var/www/gaeld
cd /var/www/gaeld
composer install --no-dev --optimize-autoloader
npm install && npm run build
cp .env.example .env
php artisan key:generate

Modifica .env con i valori di produzione (vedi Variabili d'ambiente in basso).

php artisan gaeld:install

Configurazione Nginx

server {
    listen 80;
    server_name app.example.com;
    root /var/www/gaeld/public;
    index index.php;

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

    location ~ \.php$ {
        fastcgi_pass unix:/run/php/php8.2-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }

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

Aggiungi un certificato SSL (p. es. tramite Certbot) e reindirizza la porta 80 a 443 prima di andare in produzione.

Pool PHP-FPM

Crea o modifica /etc/php/8.2/fpm/pool.d/gaeld.conf:

[gaeld]
user = www-data
group = www-data
listen = /run/php/php8.2-fpm.sock
listen.owner = www-data
listen.group = www-data
pm = dynamic
pm.max_children = 10
pm.start_servers = 2
pm.min_spare_servers = 1
pm.max_spare_servers = 3

Riavvia: systemctl restart php8.2-fpm

Worker della coda (systemd)

Gäld utilizza le code Laravel per i lavori in background (importazioni bancarie, notifiche). Avvia un worker persistente:

# /etc/systemd/system/gaeld-worker.service
[Unit]
Description=Gäld Queue Worker
After=network.target

[Service]
User=www-data
WorkingDirectory=/var/www/gaeld
ExecStart=/usr/bin/php artisan queue:work --sleep=3 --tries=3 --max-time=3600
Restart=on-failure
RestartSec=5s

[Install]
WantedBy=multi-user.target

Abilita e avvia:

systemctl enable gaeld-worker
systemctl start gaeld-worker

Attività pianificate (Cron)

Aggiungi al crontab di www-data:

* * * * * /usr/bin/php /var/www/gaeld/artisan schedule:run >> /dev/null 2>&1

Archiviazione e permessi

chown -R www-data:www-data /var/www/gaeld/storage /var/www/gaeld/bootstrap/cache
chmod -R 775 /var/www/gaeld/storage /var/www/gaeld/bootstrap/cache

I file generati (PDF delle fatture, importazioni bancarie) sono archiviati in storage/app/. In un deployment con container, monta questa directory su un volume persistente.

Variabili d'ambiente

Variabile	Descrizione	Esempio
APP_ENV	Ambiente	production
APP_URL	URL pubblico	https://app.example.com
DB_HOST	Host PostgreSQL	127.0.0.1
DB_DATABASE	Nome del database	gaeld
DB_USERNAME	Utente DB	gaeld
DB_PASSWORD	Password DB	…
REDIS_HOST	Host Redis	127.0.0.1
CACHE_DRIVER	Backend della cache	redis
QUEUE_CONNECTION	Backend della coda	redis
MAIL_MAILER	Driver di posta	smtp o mailgun
MAIL_FROM_ADDRESS	Indirizzo mittente	noreply@example.com
FEATURE_BANK_SYNC	Attiva importazione bancaria	true
FEATURE_AUTOMATION	Attiva regole automatiche	true
PLUGINS_ENABLED	Attiva i plugin	true

Aggiornamento

Dopo aver scaricato una nuova versione:

cd /var/www/gaeld
git pull
composer install --no-dev --optimize-autoloader
npm install && npm run build
php artisan gaeld:update
systemctl restart gaeld-worker

gaeld:update esegue le migrazioni in sospeso, svuota le cache e riavvia le code in modo sicuro.

Backup

Esegui il backup di:

1. Database PostgreSQL: pg_dump gaeld > gaeld_$(date +%F).sql
2. Directory di archiviazione: storage/app/ (contiene PDF generati e file caricati)
3. File .env: conservalo in modo sicuro fuori dalla root web

Si raccomanda un cron giornaliero con replica fuori sede per gli ambienti di produzione.