FAQ Installazione

Risposte alle domande piu comuni sull’installazione di XIQUIL.

Cos’e Docker e perche XIQUIL lo richiede?

Docker e un software che permette di eseguire applicazioni in “contenitori” isolati. XIQUIL usa Docker perche:

• Installazione semplice: un solo comando per avviare tutto (app + database)
• Nessun conflitto: il container include tutto il necessario, senza interferire con altri programmi
• Portabilita: funziona uguale su Windows, Mac, Linux e NAS
• Aggiornamenti sicuri: aggiornare e semplice come scaricare una nuova immagine

Non serve conoscere Docker in dettaglio — basta seguire la guida Installazione.

Quali sono i requisiti di sistema?

Componente	Minimo	Consigliato
RAM	1 GB	2 GB+
Disco	1 GB	5 GB+ (dipende da allegati e backup)
CPU	1 core	2 core+
Docker	Docker Engine 20+	Docker Desktop (ultimo)
Sistema operativo	Qualsiasi con Docker	Linux, Windows 10/11, macOS

Posso installare XIQUIL senza Docker?

No. XIQUIL e progettato per essere eseguito in Docker. Il container include il web server (nginx), l’applicazione (Python/Node.js) e si collega a un database PostgreSQL. Un’installazione manuale richiederebbe configurare tutti questi componenti separatamente.

Su quali NAS posso installare XIQUIL?

XIQUIL e stato testato su:

• Synology (DSM 7.2+ con Container Manager)
• TrueNAS SCALE (Electric Eel 24.10+)
• Unraid (6.12+ con Docker Compose Manager)

In generale, qualsiasi NAS che supporti Docker puo eseguire XIQUIL.

Posso installare XIQUIL su un Raspberry Pi?

Non ufficialmente. L’immagine Docker e compilata per architettura amd64 (x86_64). I Raspberry Pi usano architettura arm64. Un’immagine multi-architettura e in roadmap.

Quanto spazio disco serve?

L’installazione base occupa circa 800 MB (immagine Docker + database vuoto). Lo spazio aggiuntivo dipende da:

• Allegati caricati (PDF, immagini)
• Backup (se abilitati)
• Dimensione del database (cresce con i dati inseriti)

Per un uso normale, 5 GB sono piu che sufficienti.

Posso accedere a XIQUIL da fuori casa?

Si, con due opzioni:

1. VPN: configura una VPN sul tuo router o NAS e accedi come se fossi nella rete locale
2. Reverse proxy: configura un dominio e un reverse proxy (Traefik, Caddy, nginx) per accesso diretto via Internet con HTTPS — vedi Reverse proxy

Nota

La VPN e l’opzione piu sicura perche non espone XIQUIL direttamente a Internet.

Come aggiorno XIQUIL?

docker compose pull
docker compose up -d

Questo scarica l’ultima versione e riavvia l’applicazione. Il database viene migrato automaticamente. I tuoi dati non vengono cancellati.

Posso usare un database esterno?

Si. Rimuovi il servizio db dal docker-compose.yml e imposta DATABASE_URL con l’indirizzo del tuo PostgreSQL esterno:

DATABASE_URL=postgresql+psycopg://utente:password@host:5432/database

XIQUIL richiede PostgreSQL 15 o superiore.

Ho perso la password admin, come la recupero?

Opzione 1 — via CLI:

docker compose exec app sh -c "cd /app/backend && python -m app.cli reset-password --email [email protected]"

Opzione 2 — recovery mode:

ADMIN_RECOVERY=true docker compose up -d
docker compose logs app | grep RECOVERY

Questo genera un URL di reset temporaneo nei log.

Vedi anche

• Installazione — guida passo-passo all’installazione
• Installazione avanzata — NAS, reverse proxy, nativo
• FAQ Problemi comuni — errori a runtime