Problemi noti e soluzioni

Nel 90% dei casi è l'APP_KEY nel .env scritta senza il prefisso base64:. Il formato corretto è:

APP_KEY=base64:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx=

Si genera con echo "base64:$(openssl rand -base64 32)". Senza prefisso le migrazioni passano ma ogni richiesta web fallisce in cifratura ("Unsupported cipher or incorrect key length"). Conferma in docker logs itsm-fpm, correggi e applica con docker compose up -d. Stessa attenzione per APP_KEK_SECRET: dev'essere base64 di 32 byte (openssl rand -base64 32), non hex.

Se nei log di itsm-fpm vedi "password authentication failed", hai cambiato DB_PASSWORD dopo il primo avvio: PostgreSQL legge la password solo quando inizializza il volume, ai riavvii successivi conserva quella vecchia. Le migrazioni falliscono e l'entrypoint esce.

• Istanza vuota (mai funzionata, nessun dato): riparti pulito —

  docker compose -f docker-compose.production.yml down
  docker volume rm itsm_db_data itsm_redis_data
  docker compose -f docker-compose.production.yml up -d

• Istanza con dati: non cancellare nulla — riallinea la password dentro il database: docker exec itsm-db psql -U itsm -d itsm -c "ALTER ROLE itsm PASSWORD 'nuova-password';"

⚠️ E non rigenerare mai APP_KEY / APP_KEK_SECRET su un'istanza con dati: cifrano le informazioni sensibili nel database, cambiarle le rende irrecuperabili.

docker restart e docker compose restart riavviano i container con l'ambiente e i limiti vecchi: non rileggono né il .env né il compose. Per applicare le modifiche serve la ricreazione:

docker compose -f docker-compose.production.yml up -d

Compose ricrea solo i container la cui configurazione è cambiata. In caso di dubbio aggiungi --force-recreate seguito dai nomi dei servizi interessati.

itsm-web (nginx) dipende da itsm-fpm con condizione healthy: se PHP-FPM è in crash loop, Compose non lo avvia proprio. Non è lui il problema — risolvi prima la causa su itsm-fpm (vedi le voci sopra) e poi rilancia docker compose up -d: tornerà su da solo.

Stai servendo l'app in HTTP con SESSION_SECURE_COOKIE=true: il cookie di sessione viene marcato Secure e il browser lo scarta. Due configurazioni coerenti:

• Produzione dietro reverse proxy TLS: APP_FORCE_HTTPS=true + SESSION_SECURE_COOKIE=true
• Test in HTTP (es. http://localhost:8087): APP_FORCE_HTTPS=false + SESSION_SECURE_COOKIE=false

Dopo la modifica, come sempre: docker compose up -d.

Il redirect URI registrato nella console del provider deve coincidere esattamente con l'URL pubblico dell'istanza: stesso schema, stesso host, stesso percorso. Esempio per Google: https://itsm.tuodominio.it/auth/google/callback. La guida passo-passo alla configurazione OAuth è nel QUICKSTART incluso nelle istruzioni di installazione.

Sì. Al primo avvio scarica ~300 MB di firme antivirus e poi le carica in memoria: su rete lenta anche 10 minuti. Le firme restano nel volume itsm_clamav_data, quindi i riavvii successivi impiegano ~2 minuti. Nel frattempo la piattaforma funziona normalmente: la scansione degli allegati riprova da sola quando ClamAV è pronto. Per un ambiente di prova puoi anche disattivarla con ITSM_ANTIVIRUS=off (da riattivare in produzione).