Table of Contents
- Installazione su Unraid
- Requisiti
- 1. Preparare le cartelle
- 2. Creare la rete khaemhat-net
- 3. Generare la chiave segreta
- 4A. Strada A — Template Community Applications
- 4B. Strada B — Compose con il plugin Docker Compose Manager
- 5. Icona e WebUI
- 6. Accesso al registro Gitea
- 7. Primo avvio
- 8. Reverse proxy e TLS
- 9. Backup
- 10. Aggiornamento
- Problemi frequenti
- Pagine correlate
Installazione su Unraid
Stato: bozza · Ultima revisione: 2026-11-10 · Versione software: non ancora rilasciata (milestone M13) Specifica: SPEC §16.4, §16.2, §6, Appendice C · ADR 0009, ADR 0010
Khaemhat si installa su Unraid come container Docker: non esistono installer né pacchetti diversi
dall'immagine gitea.encke-hake.ts.net/balbosoft/khaemhat:<versione>. Servono due container (più un terzo
opzionale) sulla stessa rete Docker:
| Container | Immagine | Ruolo | Obbligatorio |
|---|---|---|---|
khaemhat |
gitea.encke-hake.ts.net/balbosoft/khaemhat:1.0.0 |
applicazione web (porta 8080) | sì |
khaemhat-db |
postgres:17 |
database di sistema e database delle aziende | sì |
khaemhat-redis |
redis:7 |
cache distribuita | no |
Ci sono due strade equivalenti:
- A — Template Community Applications (
deploy/unraid/khaemhat.xml): container gestiti dalla pagina Docker di Unraid, configurazione da maschera. - B — Compose (
deploy/docker-compose.unraid.yml) con il plugin Docker Compose Manager: tutti i container in un unico file, password in un file.env.
Scegli una sola strada. Se non hai preferenze, la B è più semplice da aggiornare e da replicare.
Requisiti
| Voce | Minimo consigliato |
|---|---|
| Unraid | versione con supporto alle reti Docker personalizzate e al plugin Compose (B) |
| CPU / RAM | 2 core, 4 GB liberi per Khaemhat + PostgreSQL (vedi Installazione con Docker) |
| Disco | cartelle appdata su cache SSD; spazio per database, allegati e backup locali |
| PostgreSQL | 16 o 17 (consigliato 17); il ruolo usato da Khaemhat deve avere CREATEDB |
| Accesso al registro | gitea.encke-hake.ts.net raggiungibile dal server |
1. Preparare le cartelle
Apri il terminale di Unraid e crea le cartelle persistenti:
mkdir -p /mnt/user/appdata/khaemhat/data /mnt/user/appdata/khaemhat/postgres
chown -R 99:100 /mnt/user/appdata/khaemhat/data
| Cartella sull'host | Nel container | Contenuto |
|---|---|---|
/mnt/user/appdata/khaemhat/data |
/data (khaemhat) |
allegati (files/), backup (backups/), inbox SDI (inbox/), eventuali database SQLite |
/mnt/user/appdata/khaemhat/postgres |
/var/lib/postgresql/data (khaemhat-db) |
file del database PostgreSQL |
Khaemhat scrive solo in /data; i file vengono creati con l'utente e il gruppo indicati da PUID=99 e
PGID=100 (gli utenti standard nobody:users di Unraid).
2. Creare la rete khaemhat-net
I container si parlano per nome (khaemhat-db, khaemhat-redis) solo se stanno su una rete Docker
personalizzata. Con il compose (strada B) la rete viene creata automaticamente; con il template (strada A) creala a
mano una volta:
docker network create khaemhat-net
In Settings → Docker assicurati che sia attiva l'opzione che conserva le reti personalizzate definite dall'utente, altrimenti Unraid potrebbe rimuoverla al riavvio del servizio Docker.
3. Generare la chiave segreta
KHAEMHAT_SECRET_KEY cifra le password e le connection string conservate nel database e i backup cifrati. È
obbligatoria (almeno 32 byte in base64): senza, Khaemhat non parte.
openssl rand -base64 48
Conserva la chiave fuori dal server (gestore di password, cassaforte). Se la perdi non potrai più decifrare i segreti salvati né i backup cifrati. Per cambiarla esiste una procedura guidata: vedi Aggiornamento.
4A. Strada A — Template Community Applications
Container PostgreSQL
- In Apps cerca il template ufficiale postgres e installalo con questi valori:
- Name:
khaemhat-db - Repository:
postgres:17 - Network Type: Custom: khaemhat-net
- POSTGRES_USER:
khaemhat· POSTGRES_PASSWORD: una password robusta · POSTGRES_DB:khaemhat_system - Appdata:
/mnt/user/appdata/khaemhat/postgres - variabile aggiuntiva TZ =
Europe/Rome
- Name:
- Non pubblicare la porta 5432 se non serve accedere al database dall'esterno.
- Avvia il container e controlla nei log che sia pronto ad accettare connessioni.
L'utente creato con POSTGRES_USER è proprietario del cluster e ha quindi il permesso CREATEDB, necessario a
Khaemhat per creare un database per ogni azienda.
Container Khaemhat
- In Docker → Add Container, nel campo Template URL (o con l'importazione da URL della pagina Docker)
inserisci l'URL raw del template:
https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/deploy/unraid/khaemhat.xmlIn alternativa copia il file nella cartella dei template utente di Unraid (/boot/config/plugins/dockerMan/templates-user/my-khaemhat.xml) e sceglilo dall'elenco. - Controlla i campi principali:
| Campo | Valore | Note |
|---|---|---|
| Repository | gitea.encke-hake.ts.net/balbosoft/khaemhat:1.0.0 |
sempre una versione esplicita, mai latest |
| Network | khaemhat-net |
|
| Porta web | 8080 |
cambia solo la porta host se 8080 è occupata |
| Dati | /mnt/user/appdata/khaemhat/data → /data |
|
KHAEMHAT_SYSTEM_DB |
postgres://khaemhat:<password>@khaemhat-db:5432/khaemhat_system |
campo mascherato |
KHAEMHAT_DB_SERVER |
postgres://khaemhat:<password>@khaemhat-db:5432/ |
server su cui creare i database delle aziende |
KHAEMHAT_SECRET_KEY |
la chiave del passo 3 | |
KHAEMHAT_SUPERUSER |
root (o altro nome) |
|
KHAEMHAT_SUPERUSER_PASSWORD |
password iniziale | usata solo al primo avvio |
KHAEMHAT_SUPERUSER_EMAIL |
e-mail del super utente | per il recupero password |
KHAEMHAT_COMPANY_CODE |
DEMO o il codice della tua azienda |
crea il database khaemhat_<codice> |
KHAEMHAT_COMPANY_NAME |
ragione sociale | modificabile poi dall'app |
KHAEMHAT_PUBLIC_URL |
URL pubblico, es. https://gestionale.example.com |
link nelle e-mail |
Nella sezione Show more settings trovi le variabili avanzate: KHAEMHAT_REDIS, KHAEMHAT_LICENSE_MODE,
KHAEMHAT_LICENSE, KHAEMHAT_SEED_DEMO, KHAEMHAT_UPDATE_FEED, TZ, PUID, PGID. Il significato di ogni
variabile è nella tabella di Installazione con Docker.
- Premi Apply. Il template imposta anche il controllo di salute del container (
curlsu/health/liveogni 30 secondi).
Redis (facoltativo)
Se vuoi la cache distribuita, installa un container redis:7 chiamato khaemhat-redis sulla rete
khaemhat-net, con password (--requirepass) e senza persistenza, e imposta in Khaemhat
KHAEMHAT_REDIS=redis://:<password>@khaemhat-redis:6379/0. Senza Redis Khaemhat usa la cache in memoria e funziona
allo stesso modo.
4B. Strada B — Compose con il plugin Docker Compose Manager
- Installa da Apps il plugin Docker Compose Manager.
- In Docker → Compose premi Add New Stack, chiamalo
khaemhat. - Incolla come file compose il contenuto di
deploy/docker-compose.unraid.yml(file nel repository). Il file definiscekhaemhat,khaemhat-db(postgres:17),khaemhat-redis(profiloredis, facoltativo) e la retekhaemhat-net, con i volumi in/mnt/user/appdata/khaemhat. - Nel file
.envdello stack incolla il contenuto dideploy/.env.example(file nel repository) e sostituisci i valori:
POSTGRES_PASSWORD=<password robusta per PostgreSQL>
KHAEMHAT_SECRET_KEY=<output di openssl rand -base64 48>
KHAEMHAT_SUPERUSER=root
KHAEMHAT_SUPERUSER_PASSWORD=<password iniziale, da cambiare al primo accesso>
KHAEMHAT_SUPERUSER_EMAIL=admin@example.com
KHAEMHAT_COMPANY_CODE=DEMO
KHAEMHAT_COMPANY_NAME=Khaemhat Demo S.r.l.
KHAEMHAT_PUBLIC_URL=https://gestionale.example.com
KHAEMHAT_LICENSE_MODE=production
KHAEMHAT_SEED_DEMO=false
# KHAEMHAT_REDIS=redis://:<password>@khaemhat-redis:6379/0
# REDIS_PASSWORD=<password>
- Premi Compose Up. Per avviare anche Redis, usa il profilo
redis(dal terminale:docker compose --profile redis up -dnella cartella dello stack) e decommenta le due righe di Redis nel.env.
Il file .env contiene segreti: non copiarlo in condivisioni accessibili ad altri e non metterlo in nessun
repository.
5. Icona e WebUI
Nella pagina Docker di Unraid il container mostra l'icona di Khaemhat e la voce WebUI nel menu del container:
- con il template (A) vengono dai campi
<Icon>e<WebUI>del file XML; - con il compose (B) vengono dalle etichette
net.unraid.docker.iconenet.unraid.docker.webui(http://[IP]:[PORT:8080]/); l'etichettanet.unraid.docker.managed: composemanfa riconoscere i container al plugin.
L'icona è servita come file raw dal repository pubblico:
https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/assets/icon-v1.0-256.png
(la variante con la fascia della versione major.minor). Se l'icona non compare, verifica che il server raggiunga
quell'indirizzo.
6. Accesso al registro Gitea
Il pacchetto dell'immagine è pensato come pubblico e non richiede credenziali. Se fosse reso privato, prima del primo download esegui sul server Unraid:
docker login gitea.encke-hake.ts.net
# utente: il tuo utente Gitea · password: un token di accesso con permesso di lettura dei pacchetti
Le credenziali restano salvate per i download successivi (anche quelli del pulsante di aggiornamento).
7. Primo avvio
- Avvia
khaemhat-db, poikhaemhat(il compose rispetta l'ordine da solo: l'app aspetta che PostgreSQL sia healthy). - Apri i log di
khaemhat: vedrai le migrazioni del database di sistema, la creazione del super utente e della prima azienda. - Apri la WebUI e prosegui con Primi passi.
8. Reverse proxy e TLS
Khaemhat ascolta in HTTP sulla porta 8080 e si aspetta che il TLS sia gestito da un reverse proxy (Nginx Proxy Manager, SWAG, Traefik, Caddy…). Regole:
- inoltra tutto verso
http://khaemhat:8080(se il proxy è sulla retekhaemhat-net) o versohttp://<ip>:8080; - abilita il supporto WebSocket: l'interfaccia Blazor Server usa una connessione persistente;
- passa gli header
X-Forwarded-ForeX-Forwarded-Proto; - attiva HSTS sul proxy;
- imposta
KHAEMHAT_PUBLIC_URLcon l'indirizzohttps://pubblicato, così i link nelle e-mail sono corretti.
Esempi di configurazione per i proxy più comuni sono in Installazione con Docker.
9. Backup
Usa due livelli complementari:
- Backup applicativo di Khaemhat (consigliato, è quello che permette il ripristino guidato): pianificato da
Amministrazione → Istanza e database, salva ogni database con
pg_dumpin/mnt/user/appdata/khaemhat/data/backups, con verifica, retention e copie remote (S3, WebDAV). - Plugin di backup dell'appdata di Unraid sulla cartella
/mnt/user/appdata/khaemhat, come seconda rete di sicurezza. Il plugin ferma i container durante la copia: pianificalo in un orario diverso dal backup applicativo. La copia della cartellapostgresè consistente solo se fatta a container fermo.
Procedure complete in Backup e ripristino.
10. Aggiornamento
- Leggi le note di rilascio della nuova versione nel Changelog.
- Fai un backup di tutti i database (Backup adesso).
- Con il template: Edit sul container, cambia il tag in Repository (es. da
:1.0.0a:1.0.1), Apply. Con il compose: cambia il tag nella rigaimage:e premi Compose Pull e poi Compose Up. - Controlla nei log che le migrazioni siano andate a buon fine e apri Amministrazione → Stato sistema.
Usa sempre un tag esplicito: con latest non sapresti quale versione stai eseguendo né come tornare indietro.
Rollback e casi particolari in Aggiornamento.
Problemi frequenti
| Sintomo | Causa probabile | Rimedio |
|---|---|---|
| Il container si ferma subito | variabile obbligatoria mancante | leggi l'ultimo messaggio nei log: indica la variabile |
could not translate host name "khaemhat-db" |
container non sulla stessa rete | metti entrambi su khaemhat-net |
errore di permesso su /data |
proprietario della cartella diverso da PUID/PGID |
chown -R 99:100 /mnt/user/appdata/khaemhat/data |
permission denied to create database |
ruolo PostgreSQL senza CREATEDB |
usa il ruolo proprietario o ALTER ROLE khaemhat CREATEDB |
| l'interfaccia si scollega di continuo dietro il proxy | WebSocket non abilitati | abilita il supporto WebSocket nel proxy |
unauthorized al download dell'immagine |
pacchetto privato | docker login gitea.encke-hake.ts.net |
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)