Docker Compose

Questa guida approfondisce la configurazione Docker Compose di XIQUIL per utenti che vogliono personalizzare l’installazione.

Configurazione minima (.env)

Il file .env.example di XIQUIL e volutamente ridotto a 3 variabili. Tutto il resto ha default sensati e viene auto-configurato al primo avvio (password database, JWT secret, certificato TLS, chiavi di cifratura).

# Domini o IP autorizzati ad accedere all'app
ALLOWED_HOSTS=localhost

# Porta HTTPS esposta sull'host
APP_PORT=443

# Timezone per date e orari
APP_TIMEZONE=Europe/Rome

Per la maggior parte delle installazioni, modifica solo ALLOWED_HOSTS se esponi l’app in rete, poi avvia:

docker compose up -d

Il file docker-compose.yml completo

services:
  app:
    image: ghcr.io/justvitlab/xiquil:latest
    container_name: xiquil_app
    env_file: .env
    environment:
      - PUID=${PUID:-1000}
      - PGID=${PGID:-1000}
    ports:
      - "${APP_PORT:-443}:8443"
    volumes:
      - xiquil-data:/app/data
      - xiquil-backups:/app/backups
    depends_on:
      db:
        condition: service_healthy
    restart: unless-stopped

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

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

Variabili d’ambiente

Minime (visibili nel .env.example)

Variabile	Default	Descrizione
ALLOWED_HOSTS	localhost	Domini/IP consentiti (separati da virgola)
APP_PORT	443	Porta HTTPS esterna
APP_TIMEZONE	Europe/Rome	Timezone IANA per date e orari

Avanzate (opzionali, tutte con default)

Variabile	Default	Descrizione
POSTGRES_DB	xiquil	Nome del database
POSTGRES_USER	xiquil_admin	Utente database
POSTGRES_PASSWORD	xiquil_local_db	Password database (DB su 127.0.0.1, safe per self-hosted)
DB_PORT	5432	Porta locale del DB per DBeaver/psql
PUID / PGID	1000	UID/GID nel container (TrueNAS: 568, Synology: 1026)
DATA_MOUNT	app_data	Volume/path dati app
BACKUPS_MOUNT	./backups	Volume/path backup
DB_MOUNT	pgdata	Volume/path database
ENABLE_HSTS	False	Header HSTS (solo con certificati CA-trusted)
CERT_HOSTNAME	auto	CN certificato self-signed (auto: primo host da ALLOWED_HOSTS)
BASE_URL	vuoto	URL canonico per email/export (vuoto = auto-dedotto)
UPDATE_CHECK_ENABLED	True	Controllo aggiornamenti GitHub (disabilita se air-gapped)
ADMIN_RECOVERY	vuoto	Genera URL reset password admin nei log (emergenza)
SKIP_MIGRATIONS	false	Salta migrazioni DB all’avvio (solo manutenzione)

Auto-configurate dal codice (NON servono nel .env)

Nome	Gestione automatica
DATABASE_URL	Costruita da POSTGRES_* al boot
JWT_SECRET_KEY	Generata al primo boot, salvata in /app/data/conf/jwt_secret
TOTP_ENCRYPTION_KEY	Generata al primo boot, salvata in /app/data/conf/totp_key
ALLOWED_ORIGINS	Derivata da ALLOWED_HOSTS aggiungendo https://
CERT_HOSTNAME	Derivato dal primo host di ALLOWED_HOSTS

Volumi

XIQUIL usa tre volumi:

Volume	Contenuto	Dentro il container
xiquil-data	Dati app (upload, certificati, log, plugin)	/app/data/
xiquil-backups	Backup database	/app/backups/
xiquil-db	Dati PostgreSQL	/var/lib/postgresql/

Nota

Per usare bind mount (cartelle locali) al posto di volumi Docker, sostituisci il nome del volume con il path assoluto: ./data:/app/data.

Aggiornamento

# Scarica l'ultima versione
docker compose pull

# Riavvia con la nuova versione
docker compose up -d

I dati sono nei volumi e non vengono cancellati durante l’aggiornamento. Le migrazioni del database vengono eseguite automaticamente all’avvio.

Comandi utili

# Stato dei container
docker compose ps

# Log in tempo reale
docker compose logs -f app

# Accesso diretto al database
docker compose exec db psql -U xiquil -d xiquil

# Gestione utenti da CLI
docker compose exec app sh -c "cd /app/backend && python -m app.cli list-users"

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

# Recovery admin (genera URL di reset nei log)
ADMIN_RECOVERY=true docker compose up -d
docker compose logs app | grep RECOVERY

---

Domande frequenti

Posso usare un database PostgreSQL esterno? Si. Rimuovi il servizio db dal docker-compose.yml e imposta DATABASE_URL con l’indirizzo del tuo database esterno.

Come cambio la porta? Modifica APP_PORT nel file .env o cambia direttamente nel docker-compose.yml la riga ports.

I dati sopravvivono a un docker compose down? Si, i volumi Docker vengono preservati. Solo docker compose down -v cancella i volumi (e quindi tutti i dati).