Khaemhat
Gestionale ERP + CRM per piccole e medie imprese italiane, scritto da zero in C# 14 su .NET 10 con interfaccia Blazor Server, PostgreSQL (o SQLite per demo e test) e nessuna libreria esterna. Si distribuisce solo come immagine Docker nel registro pacchetti di Gitea.
Questo file è la guida di installazione per chi sviluppa: come preparare il computer, compilare, avviare, provare e pubblicare. Chi usa il gestionale parte dalla Guida all'uso nella wiki; chi lo installa su un server da Installazione Docker o Installazione Unraid.
Stato: sviluppo in corso, versioni 0.x. Ultima milestone chiusa: M5 — Motore documenti e Vendite (0.5.0). Punto di ripresa in
docs/STATUS.md, piano in Roadmap.
1. Prerequisiti
| Strumento | Versione | A cosa serve |
|---|---|---|
| .NET SDK | 10.0.100 o successiva della stessa feature band (vedi global.json) |
compilare, provare, avviare |
| Git | qualunque recente | il repository; su Windows anche Git Bash, che esegue gli script scripts/*.sh |
| Docker | facoltativo | costruire e provare l'immagine; PostgreSQL e Redis per i test sui motori reali |
| PostgreSQL | 16 o 17, facoltativo | i test di integrazione sul motore di produzione (KHAEMHAT_TEST_PG) |
Non servono Node.js, npm, bundler, IDE particolari né pacchetti NuGet oltre a quelli ammessi: un editor qualunque
va bene (Visual Studio, Rider, VS Code con C# Dev Kit). Lingua dei messaggi del compilatore: per avere gli errori in
inglese, DOTNET_CLI_UI_LANGUAGE=en.
2. Clonare
git clone https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat.git
In rete locale anche http://192.168.30.23:3000/BalboSoft/Khaemhat.git o, con una chiave SSH,
ssh://git@192.168.30.23:2222/BalboSoft/Khaemhat.git. Il ramo principale è main; si lavora su rami
feat/<n>-descrizione, fix/…, docs/… (vedi docs/DEVELOPMENT.md).
3. Com'è fatto il repository
| Cartella | Contenuto |
|---|---|
src/Khaemhat.Core |
entità, regole, macchine a stati dei documenti, nessuna dipendenza |
src/Khaemhat.Data, .Data.Sqlite, .Data.PostgreSql |
micro-ORM, migrazioni, provider dei due motori |
src/Khaemhat.Application |
servizi applicativi: sicurezza, tabelle, anagrafiche, motore documenti, stampe, seed |
src/Khaemhat.Infrastructure |
file (PDF, fogli di calcolo, archivi), posta SMTP, cache, licenze, sicurezza: scritti in casa |
src/Khaemhat.Fiscal.Abstractions, .Fiscal.Italy |
il pacchetto paese: tutto ciò che è italiano |
src/Khaemhat.Web |
host Blazor Server, componenti, pagine, risorse dei testi in Resources/it-IT/*.json |
tests/* |
MSTest, un progetto per strato |
tools/* |
strumenti di sviluppo: licenze (LicenseTool), comuni e CAP (PlacesTool), modello dati (DataModelTool) |
docker/, deploy/ |
Dockerfile ed entrypoint; compose, .env.example, template Unraid |
scripts/ |
build, test, avvio, seed, migrazioni, pubblicazione |
docs/ |
specifica, ADR, architettura, mockup e la wiki (docs/wiki/) |
4. Compilare
scripts/build.sh
Controlla l'allowlist dei pacchetti (scripts/check-packages.sh su Directory.Packages.props) e compila
Khaemhat.sln in Release con warning come errori e gli analyzer di piattaforma. L'equivalente a mano:
dotnet build Khaemhat.sln -c Release -warnaserror
5. Avviare in locale
scripts/run-dev.sh
Avvia Khaemhat su http://localhost:5080 con SQLite in .data/dev (ignorata da git) e queste impostazioni di
sviluppo, ognuna sovrascrivibile esportando la variabile prima di lanciare lo script:
| Variabile | Valore di sviluppo |
|---|---|
KHAEMHAT_DATA_DIR, KHAEMHAT_SYSTEM_DB |
.data/dev, sqlite://…/.data/dev/system.db |
KHAEMHAT_SECRET_KEY |
una chiave fissa solo per lo sviluppo |
KHAEMHAT_SUPERUSER, KHAEMHAT_SUPERUSER_PASSWORD |
root e la password iniziale scritta nello script |
KHAEMHAT_COMPANY_CODE, KHAEMHAT_COMPANY_NAME |
DEMO, Khaemhat Demo S.r.l. |
KHAEMHAT_LICENSE_MODE |
test: tutti i moduli attivi con i codici di prova |
KHAEMHAT_SEED_DEMO |
true: la prima azienda nasce con i dati di esempio (anagrafiche, articoli, un anno di vendite) |
Al primo accesso Khaemhat chiede di cambiare la password e di collegare un'app di autenticazione (il super utente
ha la verifica in due passaggi obbligatoria): conserva la chiave e i codici di recupero. Per ripartire da zero ferma
il server e cancella .data/dev.
Altre cose utili in sviluppo:
- Invio di e-mail: senza
KHAEMHAT_SMTP_HOSTeKHAEMHAT_SMTP_FROMl'invio è spento. Per provarlo serve un server SMTP di prova sulla tua macchina, ad esempioKHAEMHAT_SMTP_HOST=127.0.0.1 KHAEMHAT_SMTP_PORT=2525 KHAEMHAT_SMTP_SECURITY=NONE KHAEMHAT_SMTP_FROM=ufficio@example.com scripts/run-dev.sh; l'esito di ogni invio è nel log, sezione E-mail/PEC. - Dati di base e di esempio su un database esistente:
scripts/seed.sh --baseoppurescripts/seed.sh --demo(aggiungono solo ciò che manca; meglio con il server fermo). - Catalogo dei componenti: http://localhost:5080/sviluppo/componenti mostra i mattoni dell'interfaccia.
- Tutte le variabili
KHAEMHAT_*sono in Installazione Docker edocs/DEPLOY.md. Una configurazione non valida ferma l'avvio con l'elenco degli errori.
Prima di ricompilare ferma il server: su Windows l'eseguibile in esecuzione blocca le DLL e la build ritenta la copia (avviso MSB3026) fino a fallire.
6. Provare
scripts/test.sh
scripts/test.sh --filter "FullyQualifiedName~Documents"
Esegue l'allowlist e tutti i test in Release. SQLite è sempre provato; i test che avviano
l'applicazione intera usano un'istanza vera su una porta libera. I test sul PostgreSQL reale partono quando
KHAEMHAT_TEST_PG indica un ruolo con CREATEDB (ogni test crea e cancella il proprio database):
docker run -d --name khaemhat-pg-test -e POSTGRES_PASSWORD=prova -p 55432:5432 postgres:17
KHAEMHAT_TEST_PG="postgres://postgres:prova@localhost:55432/postgres" scripts/test.sh
Senza la variabile quei test risultano saltati. In CI (.gitea/workflows/ci.yml) i test girano su ogni pull request verso main; il job PostgreSQL
(16 e 17) sui tag e all'avvio manuale.
Regole che i test fanno rispettare: nessun pacchetto fuori allowlist, dipendenze tra progetti nel verso giusto,
nessun testo italiano scritto nei componenti (vanno nelle risorse Resources/it-IT/*.json), chiavi di testo
esistenti, sezione del modello dati aggiornata.
7. Database e migrazioni
scripts/new-migration.sh company create_sales_documents # nuova migrazione numerata
scripts/gen-datamodel.sh # rigenera la parte generata di docs/DATA-MODEL.md
scripts/gen-datamodel.sh --check # solo verifica (la fa anche un test)
Le migrazioni si applicano da sole all'avvio, al database di sistema e a quello di ogni azienda. Il codice non deve dipendere dal motore: ogni query passa dal micro-ORM e gira identica su SQLite e PostgreSQL.
8. Immagine Docker
docker build -f docker/Dockerfile -t khaemhat:dev .
docker compose -f deploy/docker-compose.sqlite.yml up # prova veloce con SQLite
L'immagine pubblicata è gitea.encke-hake.ts.net/balbosoft/khaemhat:<versione> (e :latest, mai in produzione). La
costruisce .gitea/workflows/release.yml quando si spinge un tag vX.Y.Z (segreto REGISTRY_TOKEN con
write:package), che crea anche la release Gitea con le note del CHANGELOG.md. Se il runner non è
disponibile:
GITEA_TOKEN=… scripts/publish-image.sh v0.5.0
Non si producono installer, eseguibili o pacchetti .msi/.exe/.deb: l'unico artefatto è l'immagine
(ADR 0010). Le versioni restano 0.x finché il prodotto è in
sviluppo.
9. Documentazione e wiki
La wiki è in docs/wiki/ e si aggiorna nella stessa unità di lavoro del codice: una funzione senza documentazione
non è finita. Il workflow wiki.yml la pubblica nel wiki Gitea a ogni push su main che la tocca; a mano:
scripts/publish-wiki.sh. Le schermate stanno in docs/wiki/img/ e si fanno sull'applicazione vera con i dati di
esempio. La stessa wiki è inclusa nell'immagine e si apre con F1 dentro il gestionale.
| Cosa | Dove |
|---|---|
| Specifica normativa | docs/SPEC.md |
| Regole operative ed emendamenti | CLAUDE.md |
| Processo, rami, Definition of Done | docs/DEVELOPMENT.md |
| Architettura, dati, moduli, API, MCP | docs/ARCHITECTURE.md, docs/DATA-MODEL.md, docs/MODULES.md, docs/API.md, docs/MCP.md |
| Installazione e sicurezza | docs/DEPLOY.md, docs/SECURITY.md |
| Decisioni architetturali | docs/adr/ |
| Mockup (specifica visiva) | docs/mockups/ |
| Novità | CHANGELOG.md |
| Wiki pubblicata | https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/wiki |
10. Regole del codice in breve
- C# 14 su .NET 10,
Nullableattivo, warning come errori,.editorconfig; JavaScript solo come interop minimo inwwwroot/js. - Nessuna libreria esterna: framework Microsoft,
Npgsql,Microsoft.Data.Sqlitee, nei test, MSTest. - Codice, commenti e commit in inglese; interfaccia in italiano dalle risorse.
- Tutto ciò che è fiscale italiano sta in
Khaemhat.Fiscal.Italy. - Commit Conventional Commits che dicono cosa cambia e perché e citano l'issue (
#n); pull request versomainconCloses #n.
Il lavoro è organizzato in issue per milestone (M0-M14) e nei progetti.
Il nome viene da Khaemhat (Mahu), scriba reale e sovrintendente al doppio granaio dell'Alto e del Basso Egitto sotto Amenhotep III: vedi Origine del nome.