Installazione

Questa guida ti spiega come installare XIQUIL sul tuo computer in pochi minuti. Non serve nessuna conoscenza tecnica avanzata.

Prerequisiti

Prima di iniziare, hai bisogno di una sola cosa: Docker.

Docker e un programma che permette di eseguire applicazioni in modo isolato. Pensalo come un “contenitore” che include tutto il necessario per far funzionare XIQUIL.

Come installare Docker:

Windows: scarica Docker Desktop per Windows e segui l’installazione guidata
Mac: scarica Docker Desktop per Mac
Linux: segui la guida ufficiale per Linux
NAS (Synology, TrueNAS, Unraid): vedi la sezione Installazione avanzata

Passo 1: Crea la cartella del progetto

Crea una cartella dove vuoi installare XIQUIL. Ad esempio:

mkdir xiquil
cd xiquil

Passo 2: Crea il file docker-compose.yml

Crea un file chiamato docker-compose.yml nella cartella appena creata e incolla questo contenuto:

services:
  app:
    image: ghcr.io/justvitlab/xiquil:latest
    container_name: xiquil_app
    ports:
      - "443:8443"
    volumes:
      - xiquil-data:/app/data
      - xiquil-backups:/app/backups
    environment:
      - DATABASE_URL=postgresql+psycopg://xiquil:xiquil_password@db:5432/xiquil
      - ALLOWED_HOSTS=localhost
      - DEBUG=False
    depends_on:
      db:
        condition: service_healthy
    restart: unless-stopped

  db:
    image: postgres:18-alpine
    container_name: xiquil_db
    volumes:
      - xiquil-db:/var/lib/postgresql
    environment:
      - POSTGRES_DB=xiquil
      - POSTGRES_USER=xiquil
      - POSTGRES_PASSWORD=xiquil_password
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U xiquil"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 60s
    restart: unless-stopped

volumes:
  xiquil-data:
  xiquil-backups:
  xiquil-db:

Passo 3: Avvia XIQUIL

Apri un terminale nella cartella del progetto e digita:

docker compose up -d

Questo comando scarica le immagini necessarie e avvia XIQUIL. La prima volta ci vogliono qualche minuto per il download.

Passo 4: Apri XIQUIL nel browser

Apri il tuo browser e vai su:

https://localhost

Passo 5: Crea l’account amministratore

Al primo accesso vedrai la schermata di setup iniziale. Inserisci:

Email: il tuo indirizzo email (servira per il login)
Password: una password sicura

Clicca su “Crea account” e accederai alla dashboard.

Verifica che tutto funzioni

Dopo il login dovresti vedere la dashboard vuota, pronta per essere configurata. Complimenti, XIQUIL e installato!

Per continuare la configurazione, vai alla guida Primo avvio.

Aggiornamento

Per aggiornare XIQUIL a una nuova versione:

docker compose pull
docker compose up -d

Questo scarica l’ultima versione e riavvia l’applicazione. I tuoi dati non vengono cancellati.

Installazione nativa (senza Docker)

Se preferisci non usare Docker, XIQUIL è disponibile anche come pacchetto nativo:

Windows: installer .exe guidato (Inno Setup), avvio come servizio Windows
macOS: installer con script, avvio come LaunchDaemon + icona nella barra menu
Linux: script di installazione, avvio come unità systemd

In tutti i casi PostgreSQL è incluso nel pacchetto — non serve installarlo separatamente.

Istruzioni dettagliate: Installazione avanzata — Nativa.

Risoluzione problemi

Il browser mostra “Connessione rifiutata” Verifica che i container siano in esecuzione con docker compose ps. Se il container xiquil_app non e in stato “Up”, controlla i log con docker compose logs app.

Errore “database is not ready” Il database PostgreSQL impiega circa 60 secondi per inizializzarsi al primo avvio. Attendi un minuto e riprova.

Errore di porta occupata Un altro programma usa la porta 443. Cambia la porta nel docker-compose.yml (vedi nota al Passo 3).

Vedi anche

Primo avvio — cosa fare dopo l’installazione
Installazione avanzata — NAS, TrueNAS, reverse proxy
FAQ Installazione — problemi comuni e soluzioni