2
FAQ
Alberto Balbo edited this page 2026-11-10 22:28:47 +01:00

Domande frequenti

Stato: bozza · Ultima revisione: 2026-11-10 · Versione software: non ancora rilasciata (rilascio previsto con la milestone M13) Specifica: SPEC §1, §5.4, §6, §7, §8, §11.9, §12, §13, §16; ADR 0009, 0010

Le risposte alle domande più comuni su installazione, licenze, aziende, database, backup, fatturazione elettronica, sicurezza e aggiornamenti. Khaemhat è ancora in sviluppo: le risposte descrivono il comportamento previsto.

Installazione

Come si installa Khaemhat? Solo con Docker: l'unico pacchetto distribuito è l'immagine gitea.encke-hake.ts.net/balbosoft/khaemhat:<versione> nel registro pacchetti di Gitea. Non esistono installer, setup .exe/.msi o pacchetti per Linux. Le guide sono Installazione-Docker e Installazione-Unraid.

Cosa serve sul server? Un host Docker, un database PostgreSQL 16 o 17 (consigliato 17) per l'uso reale, un volume per i dati (/data) e un reverse proxy con HTTPS. Per una prova bastano il container e SQLite (docker-compose.sqlite.yml). Redis è facoltativo.

Dove si configura? La configurazione iniziale si fa solo con variabili d'ambiente KHAEMHAT_* (database di sistema, chiave segreta, super utente, prima azienda). Tutto il resto si imposta dal pannello Amministrazione. Khaemhat non scrive file di impostazioni: preferenze, chiavi e log stanno nel database.

Ho perso la variabile KHAEMHAT_SECRET_KEY: cosa succede? Senza chiave l'applicazione non parte, e la chiave serve a decifrare password e connessioni salvate nel database. Conservala insieme ai backup, in un posto sicuro. Per cambiarla esiste una procedura guidata di rotazione in Amministrazione → Impostazioni (vedi Impostazioni).

Al primo accesso la password del super utente non funziona più. La password indicata nelle variabili serve solo al primo avvio; al primo accesso Khaemhat chiede di cambiarla. Dopo, le variabili KHAEMHAT_SUPERUSER* vengono ignorate.

Licenze e moduli

Cosa posso usare senza licenza? Senza licenza l'istanza è in Trial: moduli Base (CORE) e Contabilità (ACCT), 3 utenti, 60 giorni, con un banner. Vedi Licenze-e-moduli.

Chi attiva i moduli? Solo il super utente, da Amministrazione → Licenze e moduli, inserendo il file di licenza o un codice di attivazione. La verifica è offline.

Cosa succede se un modulo scade o viene disattivato? Le voci di menu, le API e gli strumenti MCP del modulo spariscono e le procedure non si eseguono, ma i dati restano nel database. Oltre la scadenza e il periodo di grazia della licenza l'istanza passa in sola lettura con un banner.

I codici KH-TEST-… funzionano in produzione? No: valgono solo con KHAEMHAT_LICENSE_MODE=test, per sviluppo e prove. In produzione vengono rifiutati.

Più aziende

Posso gestire più aziende con una sola installazione? Sì. Ogni azienda ha il proprio database; le aziende condividono solo l'amministrazione (configurazione, amministratori, licenze, log di istanza). Dalla seconda azienda in poi serve il modulo MULTI. Vedi Istanza-e-database.

Gli utenti di un'azienda vedono le altre? No. Un utente aziendale è legato alla sua azienda. Solo gli account di istanza (super utente e amministratori) scelgono l'azienda dalla barra superiore.

Posso fare una copia di prova di un'azienda? Sì, con Clona: crea un database di prova (khaemhat_<codice>_test) da un backup, senza toccare l'originale.

SQLite o PostgreSQL?

SQLite PostgreSQL
Per cosa prova, demo, test, archivi in sola lettura uso quotidiano in azienda
Installazione nessun server: file nel volume /data container o server PostgreSQL 16+
Volumi di dati piccoli fino a centinaia di GB
Utenti contemporanei pochi (le scritture sono in fila) molti
Backup copia consistente del file + backup logico pg_dump + backup logico, verifica e copie remote

Il programma funziona allo stesso modo con entrambi. Per passare da SQLite a PostgreSQL si usa il backup logico (formato portabile) e lo si ripristina su un database PostgreSQL vuoto.

Backup

Khaemhat fa i backup da solo? Sì, se configuri una politica di backup in Amministrazione → Backup e ripristino: pianificazione, quante copie giornaliere/settimanali/mensili tenere, cifratura, verifica e copie remote su S3 compatibile o WebDAV. Il database di sistema è sempre incluso. Dettagli in Backup-e-ripristino.

Basta il backup del volume Docker? È utile come seconda rete di sicurezza, ma il backup applicativo è quello consigliato: è consistente, verificato, cifrato e contiene anche gli allegati dell'azienda.

Chi può ripristinare? Un amministratore avvia il ripristino, il super utente lo conferma con la verifica in due passaggi. Prima di ripristinare Khaemhat mette l'azienda in manutenzione e fa un backup di sicurezza dello stato attuale. Esiste anche la prova di ripristino, che non sostituisce nulla.

Fatturazione elettronica e SDI

Serve un intermediario per inviare le fatture? No. Khaemhat ha un canale PEC integrato: invia l'XML allo SDI dalla PEC aziendale e legge notifiche e fatture passive dalla stessa casella. In alternativa supporta SdICoop (web service dell'Agenzia, con accreditamento) e due intermediari via API. Vedi Fatturazione-elettronica.

Khaemhat "contiene" lo SDI? No: lo SDI è il sistema dell'Agenzia delle Entrate. Khaemhat prepara, valida, trasmette e riceve le fatture tramite uno dei canali.

E la conservazione a norma? Khaemhat produce un pacchetto di esportazione per periodo (XML, notifiche, indice) da affidare a un conservatore o al servizio dell'Agenzia; alcuni intermediari la includono nel servizio.

Una fattura è stata scartata: cosa faccio? Il cruscotto SDI la mostra in evidenza con il motivo dello scarto: correggi, rigenera l'XML e reinviala.

Sicurezza

Come sono protette le password? Sono salvate solo come impronta (PBKDF2-SHA256 con 600.000 iterazioni). Dopo 5 tentativi errati l'account si blocca per 15 minuti.

La verifica in due passaggi è obbligatoria? Sì per il super utente e gli amministratori; per gli utenti si decide in Amministrazione → Impostazioni.

Le password di PEC, SMTP e cloud sono al sicuro? Sono cifrate nel database con AES-256-GCM usando la chiave KHAEMHAT_SECRET_KEY.

Chi ha fatto cosa? Ogni modifica a anagrafiche, documenti, registrazioni e impostazioni finisce nello Storico del record; le azioni di sicurezza (accessi, permessi, licenze, backup, ripristini) in un registro di istanza non modificabile. Vedi Utenti-e-permessi e Log.

Serve HTTPS? Sì: Khaemhat ascolta in HTTP sulla porta 8080 dentro la rete Docker e il certificato TLS è gestito dal reverse proxy.

Aggiornamenti

Come so che c'è una nuova versione? Amministrazione → Stato sistema controlla il registro pacchetti di Gitea e mostra se è disponibile una versione più recente, con il link alle note di rilascio. L'aggiornamento non è mai automatico. Vedi Stato-sistema.

Come si aggiorna? Si cambia il tag dell'immagine con la nuova versione esplicita (mai latest in produzione) e si riavvia il container, ad esempio con docker compose pull && docker compose up -d; su Unraid dall'icona del container. Le migrazioni del database di sistema partono da sole all'avvio. Guida completa in Aggiornamento.

Posso tornare alla versione precedente? Sì, rimettendo il tag precedente; se la nuova versione ha modificato il database serve anche il ripristino del backup fatto prima dell'aggiornamento (il programma non supporta il ritorno indietro dello schema).

Il registro pacchetti richiede credenziali? Solo se il pacchetto non è pubblico: in quel caso serve docker login gitea.encke-hake.ts.net e, per il controllo aggiornamenti, un token di sola lettura in KHAEMHAT_UPDATE_TOKEN.

Pagine correlate

Primi-passi · Installazione-Docker · Installazione-Unraid · Aggiornamento · Backup-e-ripristino · Licenze-e-moduli · Glossario