Files
Khaemhat/docs/wiki/FAQ.md
T
Alby96andClaude Opus 5.5 88de272b3e docs: avoid ambiguous Unicode and record Gitea planning in STATUS
Gitea flags en dash, multiplication sign, minus sign and single angle
quotes as confusable characters, which put a warning on most pages;
use plain equivalents (docs/SPEC.md stays untouched). STATUS.md now
lists the issue numbers per milestone, the items waiting for the owner
and the open specification questions tracked by issue #114.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-10 22:44:14 +01:00

159 lines
8.3 KiB
Markdown

# 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](Installazione-Docker) e
[Installazione-Unraid](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](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](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](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](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](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](Utenti-e-permessi) e [Log](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](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](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](Primi-passi) · [Installazione-Docker](Installazione-Docker) · [Installazione-Unraid](Installazione-Unraid) ·
[Aggiornamento](Aggiornamento) · [Backup-e-ripristino](Backup-e-ripristino) · [Licenze-e-moduli](Licenze-e-moduli) ·
[Glossario](Glossario)