2
Installazione Unraid
Alberto Balbo edited this page 2026-11-10 22:28:47 +01:00

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

  1. 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
  2. Non pubblicare la porta 5432 se non serve accedere al database dall'esterno.
  3. 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

  1. 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.xml In alternativa copia il file nella cartella dei template utente di Unraid (/boot/config/plugins/dockerMan/templates-user/my-khaemhat.xml) e sceglilo dall'elenco.
  2. 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.

  1. Premi Apply. Il template imposta anche il controllo di salute del container (curl su /health/live ogni 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

  1. Installa da Apps il plugin Docker Compose Manager.
  2. In Docker → Compose premi Add New Stack, chiamalo khaemhat.
  3. Incolla come file compose il contenuto di deploy/docker-compose.unraid.yml (file nel repository). Il file definisce khaemhat, khaemhat-db (postgres:17), khaemhat-redis (profilo redis, facoltativo) e la rete khaemhat-net, con i volumi in /mnt/user/appdata/khaemhat.
  4. Nel file .env dello stack incolla il contenuto di deploy/.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>
  1. Premi Compose Up. Per avviare anche Redis, usa il profilo redis (dal terminale: docker compose --profile redis up -d nella 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.icon e net.unraid.docker.webui (http://[IP]:[PORT:8080]/); l'etichetta net.unraid.docker.managed: composeman fa 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

  1. Avvia khaemhat-db, poi khaemhat (il compose rispetta l'ordine da solo: l'app aspetta che PostgreSQL sia healthy).
  2. Apri i log di khaemhat: vedrai le migrazioni del database di sistema, la creazione del super utente e della prima azienda.
  3. 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 rete khaemhat-net) o verso http://<ip>:8080;
  • abilita il supporto WebSocket: l'interfaccia Blazor Server usa una connessione persistente;
  • passa gli header X-Forwarded-For e X-Forwarded-Proto;
  • attiva HSTS sul proxy;
  • imposta KHAEMHAT_PUBLIC_URL con l'indirizzo https:// 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:

  1. Backup applicativo di Khaemhat (consigliato, è quello che permette il ripristino guidato): pianificato da Amministrazione → Istanza e database, salva ogni database con pg_dump in /mnt/user/appdata/khaemhat/data/backups, con verifica, retention e copie remote (S3, WebDAV).
  2. 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 cartella postgres è consistente solo se fatta a container fermo.

Procedure complete in Backup e ripristino.

10. Aggiornamento

  1. Leggi le note di rilascio della nuova versione nel Changelog.
  2. Fai un backup di tutti i database (Backup adesso).
  3. Con il template: Edit sul container, cambia il tag in Repository (es. da :1.0.0 a :1.0.1), Apply. Con il compose: cambia il tag nella riga image: e premi Compose Pull e poi Compose Up.
  4. 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