4
Installazione Docker
Khaemhat CI edited this page 2026-11-11 20:02:37 +00:00

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'immagine linux/arm64 è prevista come opzione di rilascio, non garantita per ogni versione).
  • PostgreSQL 16 o 17 (consigliato 17). L'immagine contiene pg_dump/pg_restore 17, 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/backups occupano 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)

  1. Crea una cartella per l'istanza, ad esempio /opt/khaemhat, e copiaci dal repository i file deploy/docker-compose.yml e deploy/.env.example (cartella deploy/).
  2. Rinomina .env.example in .env e compila i valori (vedi sotto). Genera la chiave segreta con:
    openssl rand -base64 48
    
  3. Proteggi il file: chmod 600 .env.
  4. Avvia:
    docker compose up -d
    docker compose logs -f khaemhat
    
  5. 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 -d e KHAEMHAT_REDIS=redis://:<password>@khaemhat-redis:6379/0 nel .env;
  • puoi usare un PostgreSQL esterno (gestito dal provider cloud o già presente in azienda): togli il servizio khaemhat-db e punta KHAEMHAT_SYSTEM_DB e KHAEMHAT_DB_SERVER a quel server. Il ruolo deve avere CREATEDB perché 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-Proto e Host;
  • timeout di lettura lunghi (almeno qualche minuto) per non chiudere le connessioni inattive;
  • HSTS impostato sul proxy;
  • KHAEMHAT_PUBLIC_URL uguale all'indirizzo https:// 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):

  1. attende che il database sia raggiungibile;
  2. applica le migrazioni del database di sistema;
  3. 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);
  4. 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

  1. Primi passi: accesso del super utente, cambio password, TOTP, licenza, prima azienda.
  2. Backup e ripristino: politica di backup, copie remote, prova di ripristino.
  3. Aggiornamento: come passare alle versioni successive.

Pagine correlate