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>
159 lines
8.3 KiB
Markdown
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)
|