Installazione con Docker
Stato: bozza · Ultima revisione: 2026-11-10 · Versione software: non ancora rilasciata (milestone M13) Specifica: SPEC §6, §16.1-§16.3, Appendice C · ADR 0009, ADR 0010
Questa pagina descrive l'installazione su un qualunque host Docker: un server Linux in ufficio, una VPS, un'istanza cloud. Per Unraid c'è una pagina dedicata: Installazione su Unraid.
Khaemhat è distribuito solo come immagine Docker nel registro pacchetti di Gitea:
gitea.encke-hake.ts.net/balbosoft/khaemhat:<versione> # es. 1.0.0
Non esistono installer, pacchetti .deb/.msi o binari da scaricare. Il tag latest esiste solo come comodità
per le prove: in produzione indica sempre una versione esplicita.
Una istanza è un progetto compose: un container applicativo che serve tutte le aziende, un PostgreSQL che ospita il database di sistema e un database per azienda, e Redis facoltativo.
Requisiti
- Docker Engine con il plugin Compose v2 (
docker compose version). - Architettura
linux/amd64(l'immaginelinux/arm64è prevista come opzione di rilascio, non garantita per ogni versione). - PostgreSQL 16 o 17 (consigliato 17). L'immagine contiene
pg_dump/pg_restore17, che funzionano con server 16 e 17; con PostgreSQL 18 servirà un'immagine aggiornata. - Un reverse proxy con TLS se l'istanza è raggiungibile da Internet.
Dimensionamento
Valori indicativi per partire; vanno verificati con il carico reale (SPEC §18 fissa gli obiettivi di prestazione sulla demo moltiplicata per 10).
| Uso | Utenti contemporanei | CPU | RAM (app + PostgreSQL) | Disco |
|---|---|---|---|---|
| Prova, demo SQLite | 1-3 | 1 core | 1-2 GB | 2 GB |
| Piccola azienda | fino a 10 | 2 core | 4 GB | 20 GB + allegati + backup |
| Più aziende, magazzino e contabilità intensi | 10-50 | 4 core | 8-16 GB | 100 GB e oltre, SSD |
Regole pratiche:
- metti il volume di PostgreSQL su SSD;
- i backup locali in
/data/backupsoccupano spazio quanto la retention scelta (giornalieri + settimanali + mensili): prevedi almeno 3-4 volte la dimensione dei database, oppure sposta le copie su S3/WebDAV; - Khaemhat è un processo unico per istanza e non si scala orizzontalmente: per più carico aumenta CPU e RAM.
Installazione con PostgreSQL (consigliata)
- Crea una cartella per l'istanza, ad esempio
/opt/khaemhat, e copiaci dal repository i filedeploy/docker-compose.ymledeploy/.env.example(cartelladeploy/). - Rinomina
.env.examplein.enve compila i valori (vedi sotto). Genera la chiave segreta con:openssl rand -base64 48 - Proteggi il file:
chmod 600 .env. - Avvia:
docker compose up -d docker compose logs -f khaemhat - Quando nei log compare la conferma di avvio, apri
http://<host>:8080/(o l'URL del proxy) e prosegui con Primi passi.
Il file compose
Il file è deploy/docker-compose.yml
nel repository: applicazione, postgres:17 e redis:7 attivabile con un profilo. La versione dell'immagine si
sceglie con KHAEMHAT_VERSION nel .env. In sintesi:
services:
khaemhat:
image: gitea.encke-hake.ts.net/balbosoft/khaemhat:${KHAEMHAT_VERSION:-0.0.1}
restart: unless-stopped
depends_on:
khaemhat-db: { condition: service_healthy }
ports: ["8080:8080"]
env_file: .env
environment:
KHAEMHAT_SYSTEM_DB: postgres://khaemhat:${POSTGRES_PASSWORD}@khaemhat-db:5432/khaemhat_system
KHAEMHAT_DB_SERVER: postgres://khaemhat:${POSTGRES_PASSWORD}@khaemhat-db:5432/
TZ: Europe/Rome
volumes:
- khaemhat-data:/data
healthcheck:
test: ["CMD", "curl", "-fs", "http://localhost:8080/health/live"]
interval: 30s
timeout: 5s
retries: 3
khaemhat-db:
image: postgres:17
restart: unless-stopped
environment:
POSTGRES_DB: khaemhat_system
POSTGRES_USER: khaemhat
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
TZ: Europe/Rome
volumes:
- khaemhat-pg:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U khaemhat -d khaemhat_system"]
interval: 10s
timeout: 5s
retries: 10
khaemhat-redis:
image: redis:7
restart: unless-stopped
profiles: ["redis"]
command: ["redis-server", "--requirepass", "${REDIS_PASSWORD}", "--save", "", "--appendonly", "no"]
volumes:
khaemhat-data:
khaemhat-pg:
Note:
- la porta di PostgreSQL non è pubblicata: il database è raggiungibile solo dalla rete del progetto compose;
- per attivare Redis:
docker compose --profile redis up -deKHAEMHAT_REDIS=redis://:<password>@khaemhat-redis:6379/0nel.env; - puoi usare un PostgreSQL esterno (gestito dal provider cloud o già presente in azienda): togli il servizio
khaemhat-dbe puntaKHAEMHAT_SYSTEM_DBeKHAEMHAT_DB_SERVERa quel server. Il ruolo deve avereCREATEDBperché ogni azienda ha il proprio database.
Demo autonoma con SQLite
Per provare Khaemhat senza PostgreSQL esiste deploy/docker-compose.sqlite.yml: un solo container, database di
sistema e aziende come file SQLite nel volume /data, dati di esempio caricati al primo avvio. In sintesi:
services:
khaemhat:
image: gitea.encke-hake.ts.net/balbosoft/khaemhat:${KHAEMHAT_VERSION:-0.0.1}
ports: ["8080:8080"]
environment:
KHAEMHAT_SYSTEM_DB: sqlite:///data/system.db
KHAEMHAT_SECRET_KEY: ${KHAEMHAT_SECRET_KEY}
KHAEMHAT_SUPERUSER: root
KHAEMHAT_SUPERUSER_PASSWORD: ${KHAEMHAT_SUPERUSER_PASSWORD}
KHAEMHAT_COMPANY_CODE: DEMO
KHAEMHAT_COMPANY_NAME: Khaemhat Demo S.r.l.
KHAEMHAT_SEED_DEMO: "true"
KHAEMHAT_LICENSE_MODE: test
volumes:
- khaemhat-demo:/data
volumes:
khaemhat-demo:
docker compose -f docker-compose.sqlite.yml up
SQLite va bene per demo, prove e archivi in sola lettura. Non usarlo per lavorare con più utenti: per l'uso reale serve PostgreSQL. I dati di una demo SQLite possono essere portati su PostgreSQL con il backup logico (vedi Backup e ripristino).
Variabili di ambiente
La configurazione iniziale avviene solo con variabili d'ambiente; tutto il resto si imposta dal pannello di amministrazione e viene salvato nel database. All'avvio Khaemhat controlla le variabili e, se ne manca una obbligatoria, termina con un messaggio che indica quale.
| Variabile | Obbligatoria | Esempio / predefinito | Note |
|---|---|---|---|
KHAEMHAT_SYSTEM_DB |
sì | postgres://khaemhat:secret@khaemhat-db:5432/khaemhat_system oppure sqlite:///data/system.db |
database di sistema; ammette _FILE |
KHAEMHAT_DB_SERVER |
sì con PostgreSQL | postgres://khaemhat:secret@khaemhat-db:5432/ |
server su cui creare i database delle aziende (ruolo con CREATEDB); se assente usa host e credenziali del database di sistema |
KHAEMHAT_SECRET_KEY |
sì | base64 di almeno 32 byte | cifra i segreti nel database e i backup; per cambiarla vedi Aggiornamento |
KHAEMHAT_SECRET_KEY_NEW |
no | base64 di almeno 32 byte | solo durante la rotazione della chiave |
KHAEMHAT_SUPERUSER |
al primo avvio | root |
nome del super utente; ammette _FILE |
KHAEMHAT_SUPERUSER_PASSWORD |
al primo avvio | — | password iniziale, da cambiare al primo accesso; ammette _FILE |
KHAEMHAT_SUPERUSER_EMAIL |
al primo avvio | admin@example.com |
per il recupero password; ammette _FILE |
KHAEMHAT_COMPANY_CODE |
al primo avvio | DEMO |
codice della prima azienda (database khaemhat_demo) |
KHAEMHAT_COMPANY_NAME |
al primo avvio | Khaemhat Demo S.r.l. |
ragione sociale della prima azienda |
KHAEMHAT_COUNTRY |
no | IT |
pacchetto fiscale della prima azienda |
KHAEMHAT_LICENSE_MODE |
no | production |
test abilita i codici di licenza fittizi: mai in produzione |
KHAEMHAT_LICENSE |
no | testo della licenza .khl |
assente = Trial (CORE + ACCT, 3 utenti, 60 giorni) |
KHAEMHAT_REDIS |
no | redis://:pwd@khaemhat-redis:6379/0 (rediss:// per TLS) |
assente = cache in memoria |
KHAEMHAT_DATA_DIR |
no | /data |
allegati, backup, inbox SDI, file SQLite, export |
KHAEMHAT_URLS |
no | http://0.0.0.0:8080 |
indirizzo di ascolto; il TLS lo gestisce il proxy |
KHAEMHAT_PUBLIC_URL |
no | https://gestionale.example.com |
link nelle e-mail e nelle notifiche |
KHAEMHAT_SMTP_HOST, _PORT, _USER, _PASSWORD, _FROM, _SECURITY |
no | — | posta in uscita; sovrascrivibili da Amministrazione → Impostazioni |
KHAEMHAT_LOG_LEVEL |
no | Information |
livello minimo del log su stdout |
KHAEMHAT_SEED_BASE |
no | true |
tabelle di base alla creazione di un'azienda |
KHAEMHAT_SEED_DEMO |
no | false |
dati di esempio, solo su database vuoto |
KHAEMHAT_UPDATE_FEED |
no | https://gitea.encke-hake.ts.net/api/v1/packages/BalboSoft?type=container&q=khaemhat |
API dei pacchetti Gitea per il controllo aggiornamenti |
KHAEMHAT_UPDATE_TOKEN |
no | token Gitea in sola lettura | solo se il pacchetto non è pubblico |
KHAEMHAT_HELP_URL |
no | https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/wiki/ |
wiki online aperta da Apri nel wiki nell'aiuto; l'aiuto (F1) usa la copia della wiki contenuta nell'immagine e funziona anche senza Internet |
TZ |
no | Europe/Rome |
fuso orario |
PUID / PGID |
no | 1654 / 1654 (Unraid: 99 / 100) |
utente e gruppo proprietari dei file in /data; l'applicazione non gira mai come root |
Le variabili del super utente e della prima azienda sono lette solo al primo avvio (quando le tabelle
corrispondenti sono vuote): cambiarle dopo non ha effetto. KHAEMHAT_TEST_PG e KHAEMHAT_TEST_REDIS servono solo
ai test automatici e non vanno impostate in un'installazione.
Docker secrets
Per non scrivere le password in chiaro nel file compose, le variabili sensibili ammettono la variante _FILE: invece
del valore contengono il percorso di un file da cui leggerlo. La accettano tutte le variabili sensibili: KHAEMHAT_SYSTEM_DB,
KHAEMHAT_DB_SERVER, KHAEMHAT_SECRET_KEY, KHAEMHAT_SECRET_KEY_NEW, KHAEMHAT_SUPERUSER,
KHAEMHAT_SUPERUSER_PASSWORD, KHAEMHAT_SUPERUSER_EMAIL, KHAEMHAT_LICENSE, KHAEMHAT_REDIS,
KHAEMHAT_SMTP_PASSWORD, KHAEMHAT_UPDATE_TOKEN. Il valore è il contenuto del file senza il fine riga finale;
impostare insieme X e X_FILE è un errore che ferma l'avvio.
services:
khaemhat:
environment:
KHAEMHAT_SYSTEM_DB_FILE: /run/secrets/khaemhat_system_db
KHAEMHAT_SUPERUSER_PASSWORD_FILE: /run/secrets/khaemhat_superuser_password
secrets: [khaemhat_system_db, khaemhat_superuser_password]
secrets:
khaemhat_system_db:
file: ./secrets/system_db.txt
khaemhat_superuser_password:
file: ./secrets/superuser_password.txt
Proteggi la cartella secrets/ (chmod 700) e i file al suo interno (chmod 600).
Reverse proxy e TLS
Khaemhat non termina il TLS: ascolta in HTTP sulla porta 8080 e va pubblicato dietro un reverse proxy a tua scelta. Requisiti comuni a tutti i proxy:
- supporto WebSocket (l'interfaccia Blazor Server mantiene una connessione persistente);
- header
X-Forwarded-For,X-Forwarded-ProtoeHost; - timeout di lettura lunghi (almeno qualche minuto) per non chiudere le connessioni inattive;
- HSTS impostato sul proxy;
KHAEMHAT_PUBLIC_URLuguale all'indirizzohttps://pubblicato.
Caddy
gestionale.example.com {
reverse_proxy khaemhat:8080
}
Nginx
server {
listen 443 ssl http2;
server_name gestionale.example.com;
# ssl_certificate / ssl_certificate_key ...
add_header Strict-Transport-Security "max-age=31536000" always;
client_max_body_size 30m; # upload allegati (limite predefinito 25 MB)
location / {
proxy_pass http://127.0.0.1:8080;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_read_timeout 300s;
}
}
Con Traefik è sufficiente un router HTTPS verso il servizio khaemhat porta 8080: Traefik gestisce i WebSocket
senza configurazioni aggiuntive.
Se pubblichi l'istanza su Internet, limita la porta 8080 alla sola rete interna (o rimuovi la riga ports: e
collega il proxy alla rete del compose).
Primo avvio e log
All'avvio il container (script docker/entrypoint.sh):
- attende che il database sia raggiungibile;
- applica le migrazioni del database di sistema;
- al primo avvio crea super utente e prima azienda, applica le migrazioni dell'azienda e carica le tabelle di base (ed eventualmente i dati di esempio);
- avvia l'applicazione web.
Il log va su stdout in formato JSON, una riga per evento, e contemporaneamente nel database di sistema, dove si consulta con filtri da Amministrazione → Log. Per seguirlo da terminale:
docker compose logs -f khaemhat
docker compose logs khaemhat | grep '"level":"Error"'
Il livello minimo su stdout si cambia con KHAEMHAT_LOG_LEVEL. Khaemhat non scrive file di log su disco.
Lo stato di salute è esposto su http://<host>:8080/health/live, usato anche dal controllo di salute del
container (docker ps mostra healthy).
Dopo l'installazione
- Primi passi: accesso del super utente, cambio password, TOTP, licenza, prima azienda.
- Backup e ripristino: politica di backup, copie remote, prova di ripristino.
- Aggiornamento: come passare alle versioni successive.
Pagine correlate
Guida
Installazione
Interfaccia
Anagrafiche
Documenti
Contabilità e fisco
- Contabilità
- Chiusura e bilancio
- IVA
- Cespiti
- Intrastat
- Dichiarazioni d'intento
- Scadenzario
- Fatturazione elettronica
- Fiscalità italiana
CRM e servizi
Amministrazione
- Istanza e database
- Licenze e moduli
- Utenti e permessi
- Attività programmate
- Log
- Impostazioni
- Stato sistema
- Chiavi API e MCP
- Import/Export
- Dati di base e di esempio
Riferimento
Sviluppo
Khaemhat · ERP + CRM per PMI italiane · Repository · Issue · Roadmap · Sorgente della wiki: docs/wiki/ (le modifiche si fanno lì, non dall'editor del wiki)