TrueNAS SCALE

Guida all’installazione di XIQUIL su TrueNAS SCALE (Electric Eel 24.10+).

Prerequisiti

• TrueNAS SCALE Electric Eel 24.10+
• Accesso alla shell TrueNAS (SSH o Web Shell)
• Pool configurato con spazio disponibile

Nota

TrueNAS SCALE ha delle particolarita nella gestione Docker. Questa guida copre i problemi piu comuni e le loro soluzioni.

Attenzione

Tutti i comandi shell richiedono sudo. L’utente di default su TrueNAS SCALE non e privilegiato e i comandi docker, le operazioni sui dataset (/mnt/...) e chown/chmod falliscono senza sudo con Permission denied o output vuoto. Negli esempi sotto, anteponi sempre sudo quando esegui sul server.

Passo 1: Crea i dataset

Dalla UI TrueNAS: Storage > Create Dataset

Crea tre dataset:

• xiquil/data — per i dati dell’applicazione
• xiquil/backups — per i backup
• xiquil/db — per il database PostgreSQL

Passo 2: Configura i permessi

I dataset richiedono permessi specifici:

# Dataset app (data e backups) — utente apps di TrueNAS
sudo chown -R 568:568 /mnt/pool/xiquil/data
sudo chown -R 568:568 /mnt/pool/xiquil/backups

# Dataset db — utente postgres del container
sudo chown -R 999:999 /mnt/pool/xiquil/db

Nota

Importante: i dataset data e backups usano UID/GID 568 (utente apps di TrueNAS), mentre il dataset db usa 999 (utente postgres nel container Alpine).

Passo 3: Configura il docker-compose.yml

Adatta il docker-compose.yml standard con:

services:
  app:
    environment:
      - PUID=568
      - PGID=568
    volumes:
      - /mnt/pool/xiquil/data:/app/data
      - /mnt/pool/xiquil/backups:/app/backups

  db:
    volumes:
      - /mnt/pool/xiquil/db:/var/lib/postgresql
    healthcheck:
      start_period: 120s  # Storage lento su NAS — aumentato da 60s

Passo 4: Avvia

cd /mnt/pool/xiquil
docker compose up -d

Problemi comuni su TrueNAS

Network bloccate (zombie)

Questo e il problema piu comune su TrueNAS. Dopo un deploy fallito o un riavvio interrotto, le Docker network possono rimanere in stato “zombie”.

Soluzione dalla UI:

1. Apps > Settings > Advanced Settings > Manage Docker Configuration > Restart

Soluzione da shell (solo se hai installato l’app via Custom App YAML manuale; con TrueNAS Apps fermare/riavviare dalla UI):

sudo docker compose down --remove-orphans
sudo docker network prune -f
sudo docker compose up -d

Errore pull immagine

Se il download dell’immagine fallisce:

# Verifica connettivita
nslookup ghcr.io

# Pull manuale
sudo docker pull ghcr.io/justvitlab/xiquil:latest
sudo docker pull postgres:18-alpine

Healthcheck DB in timeout

Al primo avvio su storage lento (HDD meccanici, RAID software), PostgreSQL puo impiegare fino a 2 minuti per inizializzarsi. Aumenta start_period a 120s o 180s.

Permessi file errati

Se vedi “Permission denied” nei log, verifica che i dataset abbiano i permessi corretti (Passo 2). In TrueNAS, puoi anche impostare i permessi dalla UI: Storage > dataset > Edit Permissions.

---

Comandi diagnostici

# Stato container
sudo docker ps -a --filter name=xiquil

# Log app
sudo docker logs --tail 50 xiquil_app

# Log database
sudo docker logs --tail 50 xiquil_db

# Risorse
sudo docker stats --no-stream --filter name=xiquil

# Pulizia
sudo docker system df
sudo docker image prune -f

---

Reset completo dei dati

Se vuoi azzerare l’installazione (DB vuoto, nessun utente, nessun upload, nessuna licenza, certificati TLS rigenerati) senza disinstallare l’app dalla UI, l’unica via su TrueNAS e cancellare il contenuto dei dataset montati come volumi nei container.

Pericolo

Operazione irreversibile. Distrugge il database, tutti i file caricati, plugin e licenza attiva. I backup automatici nel dataset separato (backups) non vengono toccati e possono servire per recuperare i dati.

Procedura

1. Identifica i container (escludendo eventuali altre istanze come xiquil-test):

sudo docker ps -a | grep -i xiquil

Verifica nella colonna NAMES quale e l’istanza di produzione.

Attenzione

TrueNAS Custom App genera network con prefisso ix-<appname>_<...> (con trattini), ma i container prendono il nome dal campo container_name: del compose. Un’istanza xiquil-test puo avere container xiquil_app_test/xiquil_db_test (con underscore), che NON vengono filtrati da grep -v xiquil-test. Controlla sempre i nomi prima di operare.

2. Trova i dataset di produzione:

sudo zfs list -o name,mountpoint | grep -i xiquil | grep -vi test

Esempio output:

Mercurio/Apps/Xiquil/data       /mnt/Mercurio/Apps/Xiquil/data
Mercurio/Apps/Xiquil/database   /mnt/Mercurio/Apps/Xiquil/database
Backups/Apps/xiquil_beta        /mnt/Backups/Apps/xiquil_beta

I nomi dei dataset (db vs database, data vs Data) e dei pool variano. Lascia stare il dataset backups.

3. Ferma l’app dalla UI: Apps → Installed → seleziona la tua app → Stop, attendi STOPPED.

4. Verifica i contenuti prima di cancellare:

sudo ls -la /mnt/<pool>/Apps/Xiquil/data /mnt/<pool>/Apps/Xiquil/database

5. Svuota i contenuti (sostituisci <pool> col nome reale del tuo pool, es. Mercurio):

sudo find /mnt/<pool>/Apps/Xiquil/data -mindepth 1 -delete
sudo find /mnt/<pool>/Apps/Xiquil/database -mindepth 1 -delete

Nota

Perche find -delete e non rm -rf .../*: zsh (la shell di TrueNAS) espande il glob * prima di passare il comando a sudo. Se l’utente non ha permessi di lettura sul dataset (es. drwxrwx--- apps:apps), zsh restituisce no matches found e il comando non parte. find invece gira gia come root sotto sudo e cammina l’albero senza problemi. Il -mindepth 1 evita di cancellare anche la directory radice del dataset.

6. Verifica che siano vuoti:

sudo ls -la /mnt/<pool>/Apps/Xiquil/data /mnt/<pool>/Apps/Xiquil/database

Devi vedere solo le voci . e ...

7. Ripristina permessi numerici:

sudo chown -R 568:568 /mnt/<pool>/Apps/Xiquil/data
sudo chown -R 999:999 /mnt/<pool>/Apps/Xiquil/database

L’UID 999 (postgres del container) viene mappato sull’host TrueNAS all’utente netdata — e normale, l’importante e il valore numerico.

8. Riavvia dalla UI: Apps → Installed → app produzione → Start.

Il primo boot richiede 1-2 minuti (Postgres rifa initdb da zero). Quando lo stato e running/healthy, apri il browser sull’URL/porta dell’app — verrai indirizzato a /setup per creare il primo amministratore.

Reset selettivo: solo database

Se ti serve azzerare solo il DB mantenendo gli upload e la config:

sudo find /mnt/<pool>/Apps/Xiquil/database -mindepth 1 -delete
sudo chown -R 999:999 /mnt/<pool>/Apps/Xiquil/database

Poi riavvia l’app dalla UI.

---

Note sulla shell zsh

La shell di default su TrueNAS SCALE e zsh, che differisce da bash su alcuni punti che possono confondere il copia-incolla di comandi:

Sintassi	Cosa fa zsh	Soluzione
<placeholder>	Interpreta < come redirezione → errore	Sostituisci sempre i placeholder col valore reale prima di incollare
# commento su riga isolata	command not found: #	Rimuovi le righe di commento prima di incollare
.[!.]* o foo!	event not found (history expansion)	Quota con apici singoli o usa .??*
sudo rm /protected/*	Glob espanso PRIMA di sudo, dall’utente non privilegiato → no matches found	Usa sudo find /protected -mindepth 1 -delete
Glob senza match	Errore no matches found (in bash passerebbe il pattern letterale)	Usa find per operare su path privilegiati

Per le operazioni di reset/cleanup su /mnt/, find -delete sotto sudo e sempre la scelta sicura: aggira tutti i punti sopra ed e portabile fra zsh e bash.