Installazione su Windows (nativa)

XIQUIL su Windows si installa come servizio Windows nativo, senza Docker. L’installer .exe guidato configura PostgreSQL, certificato TLS, servizio WinSW e tray icon di controllo. Funziona offline dopo il download iniziale.

Questa guida copre l’installer dalla versione 0.21.0-beta.1-nativetest.11 in poi (la più recente al momento della scrittura). Versioni precedenti hanno un wizard più semplice e mancano di alcune protezioni.

Requisiti

• Windows 10/11 (64-bit) — minimo Windows 10 build 1809
• 4 GB RAM minimo (8 GB raccomandati)
• 800 MB di spazio disco per applicazione + Python embedded; +400 MB se usi PostgreSQL bundled
• Privilegi di Amministratore (l’installer si auto-eleva con UAC)
• Connessione internet solo per scaricare l’installer — l’installazione è completamente offline

Download

Vai su Releases di GitHub e scarica:

• XIQUIL-Setup-X.Y.Z.exe (~400 MB) — include Python 3.13 embedded + PostgreSQL 18 silent installer + frontend compilato

SmartScreen di Windows Defender

L’installer non è firmato Authenticode (in roadmap per la stable). Al primo avvio Windows mostra “Windows ha protetto il PC”. Clicca “Ulteriori informazioni” → “Esegui comunque”.

Installazione (fresh)

Avvia l’installer come amministratore (tasto destro → “Esegui come amministratore”). Il wizard rileva automaticamente se è una prima installazione o un upgrade leggendo XIQUIL_VERSION= da %PROGRAMDATA%\XIQUIL\data\conf\xiquil.env.

1. Modalità di installazione

Una volta accettata la licenza GNU AGPL v3 e scelta la cartella (default C:\Program Files\XIQUIL\), appare una pagina con tre opzioni:

Modalità	Cosa fa
Solo questo PC	Bind su 127.0.0.1, niente firewall, autostart tray. Consigliata per uso personale sul singolo PC.
Anche da smartphone/altri PC	Bind su 0.0.0.0, regola firewall TCP 8443 aperta, autostart tray. Per accesso da rete locale.
Installazione avanzata	Mostra le pagine di configurazione manuale: scelta sorgente PostgreSQL, host/porta DB, host applicativo, hosts consentiti.

In modalità Solo questo PC o Anche da smartphone, l’installer auto-risolve PostgreSQL bundled con porta 5432 e password applicativo autogenerata. Se rileva che hai già PostgreSQL installato, mostra un avviso e ti chiede di passare a “Installazione avanzata” per inserire la password del superuser postgres.

2. Verifica porta PostgreSQL libera

Prima di lanciare il setup silenzioso di PostgreSQL EDB, l’installer sonda la porta 5432. Se è occupata (Docker container, pgBouncer, vecchio PostgreSQL non rimosso), mostra:

La porta TCP 5432 è già in uso su questo PC.
PostgreSQL non può essere installato su una porta occupata. Cause tipiche:
  • Docker Desktop con un container che espone la porta 5432
  • Un'altra installazione di PostgreSQL (diversa versione)
  • Servizi come pgBouncer, pgAdmin, o simili

In modalità Solo questo PC / Anche da smartphone ti redirige automaticamente alla “Installazione avanzata” dove puoi cambiare la porta. In modalità avanzata blocca il pulsante “Avanti” finché non risolvi il conflitto o cambi la porta.

3. Pagine “Installazione avanzata”

Solo se hai scelto Installazione avanzata:

Server PostgreSQL

Campo	Default	Note
Host	127.0.0.1	127.0.0.1 o localhost per locale, IP/hostname per remoto
Porta	5432 (o quella rilevata)	Se installi bundled e la 5432 è occupata, scegli 5433/5442/altro
Password superuser postgres	(richiesta solo se PG esistente o remoto)	Serve per creare il database applicativo. Non chiesta per il bundled (auto-generata)

Database applicativo

Campo	Default	Note
Nome database	xiquil
Utente proprietario	xiquil_admin
Password applicativo	autogenerata	Mostrata in chiaro nel riepilogo finale — salvala. Scritta in xiquil.env

Rete

Campo	Default	Note
Porta HTTPS	8443	443 richiede sempre admin e può confliggere con IIS/Skype. 8443 è la default consigliata
Indirizzo di ascolto	127.0.0.1	0.0.0.0 per LAN. Cambia anche ALLOWED_HOSTS di conseguenza
Hostname consentiti	localhost,NOME-PC	Aggiungi IP LAN se accedi da altri device (es. 192.168.1.10)

4. Riepilogo

Schermata con tutti i parametri risolti e la password DB autogenerata in chiaro. Salvala — è scritta solo nel file xiquil.env, se lo perdi non c’è recupero.

5. Account amministratore

L’installer non chiede email/password admin. Il primo accesso al browser ti porta a /setup con misuratore di robustezza password e validazioni. Single source of truth per la policy password.

Cosa fa l’installer in dettaglio

In ordine, durante la fase “Installazione in corso”:

1. Copia file in C:\Program Files\XIQUIL\ (Python embedded, backend, frontend dist, desktop scripts, WinSW)
2. Pulizia orfani da installazioni precedenti (es. healthcheck.ps1 rimosso in nativetest.11)
3. Backup pre-upgrade (solo upgrade, se checkbox attivo): pg_dump → %PROGRAMDATA%\XIQUIL\backups\pre_upgrade_*.dump
4. Install PostgreSQL bundled (solo se scelto): EDB silent installer con superpassword autogenerata. Su upgrade questo step è saltato
5. Crea database e ruolo (solo fresh): CREATE ROLE xiquil_admin … CREATE DATABASE xiquil OWNER xiquil_admin. SQL idempotente con ALTER ROLE se esiste già
6. Scrive xiquil.env in %PROGRAMDATA%\XIQUIL\data\conf\ con tutti i parametri + marker POSTGRES_INSTALLATION=bundled|existing|remote
7. Genera certificato TLS self-signed via cryptography Python lib (auto-rinnovato se < 30 giorni)
8. Esegue migrazioni Alembic — durante questo step lo StatusLabel dice “può richiedere diversi minuti, non chiudere l’installer”. Il FilenameLabel punta al log live in %PROGRAMDATA%\XIQUIL\data\logs\
9. Installa servizio WinSW chiamato XIQUIL (auto-start delayed)
10. Avvia servizio se i passi DB sono ok
11. Regola firewall (solo se LAN o task selezionato): netsh advfirewall firewall add rule name="XIQUIL Server" localport=8443
12. Healthcheck post-install (vedi sezione dedicata)

Up-and-running checklist finale

Quando il healthcheck passa tutti e 5 i controlli, l’installer:

1. Lancia il tray XIQUIL via ExecAsOriginalUser (de-eleva i privilegi — l’installer gira admin, ma pystray deve girare come utente per essere visibile in systray)
2. Apre il browser su https://localhost:8443 via ShellExec
3. Mostra una MsgBox di successo con 5 bullet verdi:

   Installazione completata. XIQUIL è operativo:
     - Servizio Windows: avviato
     - Backend: raggiungibile
     - Database: connesso
     - Tray icon: attiva nella barra di sistema
     - Browser: aperto su https://localhost:8443

Se qualcosa fallisce, né tray né browser vengono lanciati — vedi solo la MsgBox specifica per l’errore. Nessuna falsa promessa di “tutto a posto”.

Healthcheck post-install (cross-platform)

Lo script desktop/healthcheck.py è lo stesso usato anche su Linux (cross-platform Python stdlib). Esegue 5 controlli sequenziali con timeout 120s:

#	Controllo	Strumento	Exit code se fallisce
1	Servizio registrato	sc query XIQUIL	2
2	Servizio raggiunge Running	poll sc query ogni 2s	3
3	Porta TCP bound su 127.0.0.1	socket.create_connection	4
4	HTTPS GET /api/system/version → 200	urllib + trust-all SSL	1 (soft warn)
5	HTTPS GET /health → 200 con database: "connected"	come sopra, parse JSON	5

Ogni exit code è mappato a una MsgBox specifica in italiano che ti dice esattamente cosa è andato storto e dove cercare. Esempio per exit 5:

Il backend XIQUIL risponde ma non riesce a connettersi a PostgreSQL.
Cause tipiche:
  - Password del database errata
  - Servizio PostgreSQL non in esecuzione
  - PostgreSQL in ascolto su porta diversa da quella configurata
Verifica:
  - %PROGRAMDATA%\XIQUIL\data\conf\xiquil.env (POSTGRES_HOST/PORT/PASSWORD)
  - Servizi Windows: controlla che "postgresql-18" sia in Running
  - %PROGRAMDATA%\XIQUIL\data\logs\app-*.log per l'errore DB preciso

Il healthcheck scrive un log persistente in %PROGRAMDATA%\XIQUIL\data\logs\healthcheck-YYYYMMDD_HHMMSS.log. Puoi rieseguirlo manualmente in qualsiasi momento:

& "C:\Program Files\XIQUIL\python\python.exe" `
  "C:\Program Files\XIQUIL\desktop\healthcheck.py" --port 8442 --timeout 30

Aggiornamento (upgrade)

Scarica il nuovo .exe ed eseguilo come admin. L’installer rileva l’installazione esistente e mostra una sola schermata “Aggiornamento rilevato” con:

• Versione attuale → nuova versione
• Checkbox “Esegui un backup del database prima di aggiornare” (default ON, raccomandato)

Cosa fa durante l’upgrade:

1. Backup pre-upgrade in %PROGRAMDATA%\XIQUIL\backups\pre_upgrade_*.dump se checkbox attivo
2. Kill processi residui: ferma il servizio WinSW + polla Status=Stopped per 30s + taskkill su python.exe/pythonw.exe con ExecutablePath o CommandLine contenente XIQUIL o tray_app. Questa mossa è cruciale: senza, WinSW 2.x ha stopTimeoutInSec di 15s e i child python continuerebbero a tenere il lock su libcrypto-3.dll causando “DeleteFile fallito codice 5 — Accesso negato”
3. Sovrascrive i file ([Files])
4. Riapplica le migrazioni (init_migrate)
5. Reinstalla e riavvia il servizio
6. Healthcheck come fresh install

L’env file non viene sovrascritto durante l’upgrade (preserva tue modifiche manuali). Solo il marker XIQUIL_VERSION= viene aggiornato. Se manca POSTGRES_INSTALLATION= (upgrade da nativetest.10 o precedenti), viene aggiunto inferendolo dal registry PostgreSQL.

Downgrade bloccato

L’installer rifiuta versioni precedenti a quella installata: le migrazioni database non sono reversibili. Per fare downgrade reale: disinstalla, ripristina un backup, installa la versione voluta.

Disinstallazione

Da “Installazione applicazioni” di Windows, cerca “XIQUIL” → Disinstalla. Dopo la conferma standard di Inno Setup, appare una pagina custom con 2 checkbox (entrambi OFF di default — re-install friendly):

La cartella %PROGRAMDATA%\XIQUIL (dati, log, backup, configurazione)
sarà conservata per un'eventuale reinstallazione.

All'inizio della disinstallazione verrà creato un backup del database in
%PROGRAMDATA%\XIQUIL\backups\pre_uninstall_<timestamp>.dump
(se PostgreSQL è raggiungibile).

Seleziona qui sotto cosa rimuovere in AGGIUNTA ai file dell'applicazione:

[ ] Rimuovi PostgreSQL 18 bundled (installato da XIQUIL)
    Implica rimozione automatica del database.

[ ] Rimuovi database xiquil (DROP DATABASE + ruolo xiquil_admin)
    Richiede la password del superuser "postgres".

Logica:

• Tick “Rimuovi PG” → forza-tick “Rimuovi DB” e lo blocca grigio (l’unins di EDB cancella comunque il data dir). Disponibile solo se il marker POSTGRES_INSTALLATION=bundled (PG installato dall’installer); disabilitato altrimenti.
• Tick solo “Rimuovi DB” → si abilita il campo password superuser. Vuoto = drop saltato con avviso (l’uninstall continua).

Sequenza eseguita:

1. Backup precauzionale del DB (sempre, se PG raggiungibile)
2. Kill tray + stop service WinSW + polling stop + kill python residui
3. Se “Rimuovi DB” senza “Rimuovi PG”: pg_terminate_backend() + DROP DATABASE + DROP ROLE come postgres superuser
4. Se “Rimuovi PG”: uninstall-postgresql.exe --mode unattended
5. Rimozione regola firewall
6. %PROGRAMDATA%\XIQUIL\ mai toccato (database xiquil_admin, certs, log, backup, config preservati)
7. Inno rimuove C:\Program Files\XIQUIL\

Per pulizia totale dopo la disinstallazione, elimina manualmente:

Remove-Item -Recurse -Force "$env:ProgramData\XIQUIL"

Tray icon

L’icona nella barra di sistema mostra lo stato del servizio:

Icona	Stato
Verde	Running
Giallo	Avvio in corso
Rosso	Stopped
Grigio	Sconosciuto (problema di comunicazione con WinSW — apri tray.log)

Menu contestuale (clic destro):

• Apri nel browser — webbrowser.open('https://localhost:<porta>')
• Avvia/Arresta/Riavvia servizio — abilitati dinamicamente in base allo stato
• Apri cartella log — %PROGRAMDATA%\XIQUIL\data\logs\
• Apri cartella dati — %PROGRAMDATA%\XIQUIL\
• Esci — chiude solo il tray, il servizio continua

Doppio-click sull’icona = “Apri nel browser” (azione default).

L’autostart al login è gestito da uno shortcut in {userstartup} (cartella autostart utente, NON di sistema), creato di default. Per disabilitare: rimuovi %APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup\XIQUIL Tray.lnk.

Tray icon grigia o menu sbagliato?

Apri %PROGRAMDATA%\XIQUIL\data\logs\tray.log. Se vedi _run_winsw failed: FileNotFoundError, il path al servizio WinSW non è corretto — assicurati di avere nativetest.12 o successivo (fix del path resolution).

Accesso dalla rete locale (LAN)

Se in fase di install hai scelto “Anche da smartphone/altri PC” è già tutto configurato. Se hai scelto “Solo questo PC” e vuoi cambiare:

1. Modifica %PROGRAMDATA%\XIQUIL\data\conf\xiquil.env:

   APP_HOST=0.0.0.0
   ALLOWED_HOSTS=localhost,NOME-PC,192.168.1.10

2. Aggiungi la regola firewall (PowerShell admin):

   netsh advfirewall firewall add rule name="XIQUIL Server" `
     dir=in action=allow protocol=TCP localport=8443

3. Riavvia il servizio:

   sc stop XIQUIL ; Start-Sleep -Seconds 5 ; sc start XIQUIL

Da un altro device della LAN, apri https://192.168.1.10:8443.

Percorsi dei file

Contenuto	Percorso
Applicazione	C:\Program Files\XIQUIL\
Python embedded	C:\Program Files\XIQUIL\python\
Backend Python	C:\Program Files\XIQUIL\backend\
Frontend compilato	C:\Program Files\XIQUIL\frontend\dist\
Servizio WinSW	C:\Program Files\XIQUIL\service\xiquil-service.exe
Tray app	C:\Program Files\XIQUIL\tray\tray_app.py
Healthcheck	C:\Program Files\XIQUIL\desktop\healthcheck.py
Configurazione	C:\ProgramData\XIQUIL\data\conf\xiquil.env
Certificati TLS	C:\ProgramData\XIQUIL\data\certs\
Upload utente	C:\ProgramData\XIQUIL\data\uploads\
Log applicazione (ruotati)	C:\ProgramData\XIQUIL\data\logs\app-YYYY-MM-DD.log
Log servizio (WinSW)	C:\ProgramData\XIQUIL\data\logs\xiquil-service.{out,err,wrapper}.log
Log healthcheck	C:\ProgramData\XIQUIL\data\logs\healthcheck-*.log
Log tray	C:\ProgramData\XIQUIL\data\logs\tray.log
Log installer	C:\ProgramData\XIQUIL\data\logs\install-*.log
Backup database	C:\ProgramData\XIQUIL\backups\

Comandi utili

# Stato servizio
sc query XIQUIL

# Avvia/arresta manualmente
net start XIQUIL
net stop XIQUIL

# Healthcheck cross-platform (esegue gli stessi 5 step dell'installer)
& "C:\Program Files\XIQUIL\python\python.exe" `
  "C:\Program Files\XIQUIL\desktop\healthcheck.py" --port 8442 --timeout 30

# Log applicazione (ultimo del giorno)
Get-Content "$env:ProgramData\XIQUIL\data\logs\app-$(Get-Date -Format yyyy-MM-dd).log" -Tail 100

# Quale processo tiene una porta
Get-NetTCPConnection -LocalPort 8442 -State Listen

# Quale porta usa PostgreSQL
Get-Process postgres -EA SilentlyContinue | ForEach-Object {
  Get-NetTCPConnection -OwningProcess $_.Id -State Listen -EA SilentlyContinue
} | Select-Object -Unique LocalAddress, LocalPort

# Lista utenti applicativi
& "C:\Program Files\XIQUIL\python\python.exe" -m app.cli list-users

# Reset password admin
& "C:\Program Files\XIQUIL\python\python.exe" -m app.cli reset-password --email admin@example.com

Risoluzione problemi

Installer fallisce con “DeleteFile fallito codice 5” (Accesso negato)

Significa che un processo XIQUIL sta tenendo aperto un file dell’install dir (tipicamente C:\Program Files\XIQUIL\python\libcrypto-3.dll). Versioni .7+ dell’installer fanno kill esplicito dei python residui, ma se ti capita su un upgrade molto vecchio:

sc stop XIQUIL
Start-Sleep -Seconds 5
Get-Process python,pythonw -EA SilentlyContinue | Where-Object { $_.Path -like '*XIQUIL*' } | Stop-Process -Force

Poi clicca Riprova nel dialog dell’installer.

Installer fallisce con “Installazione di PostgreSQL fallita (codice 1)”

La porta 5432 è occupata. Vedi %PROGRAMDATA%\XIQUIL\data\logs\install-*.log — l’installer dovrebbe averti già mostrato la MsgBox port-conflict. Soluzione:

• Ferma chi tiene 5432: Get-NetTCPConnection -LocalPort 5432 -State Listen
• Oppure rilancia in Installazione avanzata scegliendo una porta diversa (es. 5433, 5442)

Servizio “Running” ma non risponde sulla porta

Healthcheck exit code 3 o 4. Diagnosi:

# Cosa sta facendo il backend?
Get-Content "$env:ProgramData\XIQUIL\data\logs\app-$(Get-Date -Format yyyy-MM-dd).log" -Tail 100

# Il servizio è davvero running?
sc query XIQUIL

# Wrapper WinSW log (cause restart-loop)
Get-Content "$env:ProgramData\XIQUIL\data\logs\xiquil-service.wrapper.log" -Tail 30

Causa frequente: password DB errata in xiquil.env. Verifica con:

$env:PGPASSWORD = (Get-Content "$env:ProgramData\XIQUIL\data\conf\xiquil.env" |
  Select-String '^POSTGRES_PASSWORD=').Line -replace '^POSTGRES_PASSWORD=', ''
& "C:\Program Files\PostgreSQL\18\bin\psql.exe" -h 127.0.0.1 -p 5434 -U xiquil_admin -d xiquil -c "SELECT 1"

Backend risponde ma /health ritorna 503

Healthcheck exit code 5. Il backend è up ma non riesce a connettersi al DB. Cause comuni:

• Password DB nell’env non matcha quella nel role PostgreSQL (succede dopo install multipli sullo stesso PC)
• Servizio PostgreSQL fermo (sc query postgresql-18)
• POSTGRES_PORT nell’env diverso da quello su cui PG sta in ascolto

Per riallineare le password (con la password superuser postgres):

$xiqPwd = (Get-Content "$env:ProgramData\XIQUIL\data\conf\xiquil.env" |
  Select-String '^POSTGRES_PASSWORD=').Line -replace '^POSTGRES_PASSWORD=', ''
$env:PGPASSWORD = Read-Host "Password postgres superuser"
& "C:\Program Files\PostgreSQL\18\bin\psql.exe" -h 127.0.0.1 -p 5434 -U postgres `
  -c "ALTER USER xiquil_admin WITH PASSWORD '$xiqPwd';"

Browser mostra solo JSON {"app":"XIQUIL","version":"...","status":"running"}

Stai visitando la root del backend invece della SPA React. Vai su https://localhost:8442/login (o aggiungi /setup per la prima configurazione admin). Versioni .12+ rimuovono questo problema rendendo / la SPA in native mode.

Tray icon resta grigia / “Avvia servizio” attivo anche se il servizio è running

Il tray non riesce a contattare WinSW. Apri %PROGRAMDATA%\XIQUIL\data\logs\tray.log — se vedi _run_winsw failed, hai una versione precedente alla .12 (path resolution bug). Aggiorna all’ultima.

Voglio rimuovere completamente XIQUIL incluso PostgreSQL bundled

In disinstallazione, tick entrambe le checkbox + inserisci la password postgres se richiesta. Dopo:

Remove-Item -Recurse -Force "$env:ProgramData\XIQUIL"

Per il caso “PG bundled non disponibile come opzione di rimozione” (vecchio install senza marker), la pagina di disinstallazione mostra il motivo nel testo del checkbox.