Skip to Content
Getting StartedCommunity Edition

Guida Introduttiva: Community Edition

La Community Edition (CE) di SagraFacile ti permette di eseguire l’intera piattaforma sulla tua infrastruttura locale. Questa versione è gratuita.

Panoramica

Con la Community Edition:

  • Controllo completo: i dati rimangono sulla tua infrastruttura
  • Funzionamento offline: continua a lavorare anche senza internet
  • Gratuito: disponibile per il download su sagrafacile.it/releases 

La Community Edition richiede conoscenze tecniche per l’installazione e la manutenzione. Se preferisci una soluzione gestita, considera la versione Cloud.

Prerequisiti

Prima di iniziare, assicurati di avere:

Software Richiesto

  • Docker Desktop: necessario per eseguire l’applicazione — scarica qui 
  • PowerShell: già incluso in Windows 10 e versioni successive. Necessario per gli script di configurazione
  • Un editor di testo: VS Code, Notepad++ o anche Blocco Note

Requisiti di Rete

  • Dominio su Cloudflare: il tuo dominio deve essere gestito tramite Cloudflare per ottenere certificati SSL validi
  • Accesso al router: per configurare il DNS locale

Requisiti Hardware (Consigliati)

  • CPU: 2+ core
  • RAM: 4+ GB
  • Storage: 20+ GB disponibili
  • Rete: connessione Ethernet stabile (consigliata rispetto al Wi-Fi)

Configurazione della Rete

Una corretta configurazione della rete è essenziale per il funzionamento di SagraFacile su tutti i dispositivi della tua rete locale.

Assegna un IP Statico al Server

Configura il computer che ospiterà SagraFacile con un indirizzo IP locale statico (es. 192.168.1.10). Questo garantisce che l’indirizzo non cambi dopo un riavvio.

Configura il DNS su Cloudflare

  1. Accedi al tuo account Cloudflare
  2. Crea un record DNS di tipo A che punti all’indirizzo IP pubblico della tua rete
  3. Questo è necessario per la validazione del certificato SSL

Configura il DNS Locale sul Router

Configura il tuo router per risolvere il tuo dominio (es. sagrafacile.tuaorganizzazione.it) all’indirizzo IP locale del server (es. 192.168.1.10).

Questa funzione è spesso chiamata:

  • “Local DNS”
  • “DNSMasq”
  • “Static Hostname”
  • “DNS Rebinding”

Senza questa configurazione, i dispositivi sulla tua rete locale cercheranno di connettersi all’IP pubblico invece che al server locale, causando problemi di connessione.

Installazione

Scarica SagraFacile

Scarica l’ultima versione del pacchetto dalla pagina Releases  ed estrailo in una cartella (es. C:\sagrafacile).

Crea un API Token su Cloudflare

  1. Vai su Cloudflare: My Profile > API Tokens > Create Token
  2. Usa il template “Edit zone DNS”
  3. Permessi: Zone:DNS:Edit
  4. Risorse: Seleziona il tuo dominio specifico
  5. Copia il token generato

Esegui lo Script di Configurazione

Apri il Prompt dei comandi (o PowerShell) nella cartella di SagraFacile ed esegui:

start.bat

Lo script rileva automaticamente se è il primo avvio o un avvio successivo:

  • Primo avvio: guida interattiva completa, crea il file sagrafacile_config.json
  • Avvii successivi: usa la configurazione salvata. Puoi scegliere se usarla così com’è o riconfigurare

Durante la configurazione lo script chiede:

CampoDescrizione
Nome di dominioEs. sagrafacile.tuaorganizzazione.it
API Token CloudflarePer ottenere i certificati SSL
Utente PostgreSQLCredenziale database (default: sagrafacile)
Password PostgreSQLCredenziale database
Nome database(default: sagrafaciledb)
JWT SecretChiave di sicurezza — può essere generata automaticamente
Seed dati demoCarica dati di esempio per testare l’applicazione
Nome organizzazioneNome del tuo evento o associazione
Email adminEmail dell’amministratore principale
Password adminPassword per l’account admin

Selezionando No al seed demo, ti verrà chiesto di inserire i dati della tua organizzazione. Selezionando Sì, verrà caricato un dataset di esempio (utile per valutare le funzionalità).

Alla fine dello script è disponibile una sezione Configurazione Avanzata (opzionale):

CampoDescrizioneDefault
JWT IssuerIdentificatore dell’emittente del tokenSagraFacile
JWT AudienceIdentificatore del destinatario del tokenSagraFacileApp
PreOrder Polling ServiceAbilita il servizio di polling per i preordinitrue
Queue Display Customer QR (PUBLIC_QUEUE_QR_ENABLED)Mostra il QR cliente nelle pagine Display Coda pubblichefalse
Cloudflare EmailEmail Cloudflare (solo per alcuni plugin DNS)—

Attendi l’Avvio dei Servizi

Lo script avvierà Docker Compose e tutti i servizi necessari. Al primo avvio:

  • Verranno scaricate le immagini Docker (può richiedere alcuni minuti)
  • Caddy otterrà automaticamente un certificato SSL da Let’s Encrypt
  • Il database verrà inizializzato

Struttura dei File

Dopo l’installazione, la cartella avrà questa struttura:

    • docker-compose.yml
    • Caddyfile
    • .env
    • sagrafacile_config.json
    • start.bat
    • start.sh
    • stop.bat
    • stop.sh
    • update.bat
    • update.sh
FileDescrizione
docker-compose.ymlConfigurazione dei servizi Docker
CaddyfileConfigurazione del reverse proxy e SSL
.envVariabili d’ambiente (generato automaticamente da start.*)
sagrafacile_config.jsonConfigurazione salvata — riletta ad ogni avvio successivo
start.*Avvia i servizi (e gestisce la configurazione al primo avvio)
stop.*Ferma i servizi
update.*Aggiorna le immagini Docker all’ultima versione

Non modificare .env manualmente: viene rigenerato dallo script start.* ad ogni avvio. Tutte le modifiche alla configurazione vanno fatte rieseguendo start.* e scegliendo l’opzione di riconfigurazione.

Accesso a SagraFacile

Una volta che i servizi sono attivi:

Apri il browser

Da qualsiasi dispositivo connesso alla tua rete locale, naviga a:

https://tuo.dominio.com

Sostituisci tuo.dominio.com con il dominio che hai configurato.

Effettua il login

Usa le credenziali configurate durante l’installazione (email e password admin).

Pagina di login

Accedi alla Dashboard

Dopo il login, verrai reindirizzato alla dashboard di amministrazione dove potrai iniziare a configurare il tuo evento.

Gestione dei Servizi

Avviare i Servizi

Esegui start.* dalla cartella di SagraFacile:

start.bat

Se esiste già un file sagrafacile_config.json, lo script chiederà se usare la configurazione esistente o riconfigurare. Premi Invio (o digita 1) per avviare con la configurazione salvata.

Fermare i Servizi

stop.bat

Aggiornare i Servizi

Per aggiornare SagraFacile a una nuova versione:

Scarica il nuovo pacchetto

Scarica il nuovo ZIP dalla pagina Releases  ed estrailo in una cartella temporanea.

Sostituisci docker-compose.yml

Copia il file docker-compose.yml dalla cartella temporanea nella cartella di SagraFacile, sovrascrivendo quello esistente. Questo è necessario perché ogni release fissa la versione delle immagini Docker.

Esegui lo script di aggiornamento

update.bat

Lo script scarica le nuove immagini Docker e riavvia i servizi. La configurazione e i dati esistenti vengono preservati automaticamente.

Puoi anche aggiornare gli altri file (script start.*, stop.*, update.*) dal nuovo ZIP, ma non è obbligatorio se funzionano correttamente.

Riconfigurare

Per modificare qualsiasi impostazione (dominio, credenziali, JWT secret, ecc.), riesegui start.* e scegli l’opzione 2 - Re-configure SagraFacile. La configurazione salvata verrà mostrata come default per ogni campo.

Visualizzare i Log

docker compose logs -f

Per visualizzare i log di un servizio specifico:

docker compose logs -f api      # Log del backend
docker compose logs -f frontend # Log del frontend
docker compose logs -f caddy    # Log del reverse proxy
docker compose logs -f db       # Log del database

Risoluzione Problemi

Il certificato SSL non viene ottenuto

Se Caddy non riesce a ottenere il certificato SSL, verifica che:

  • Il record DNS su Cloudflare punti correttamente al tuo IP pubblico
  • L’API Token di Cloudflare sia valido e abbia i permessi corretti (Zone:DNS:Edit)
  • Le porte 80 e 443 siano raggiungibili dall’esterno (solo durante l’ottenimento del certificato)

Controlla i log di Caddy per maggiori dettagli:

docker compose logs -f caddy

I dispositivi non riescono a connettersi

Verifica che:

  1. Il DNS locale sia configurato correttamente sul router
  2. Tutti i dispositivi siano sulla stessa rete locale
  3. Il firewall del server non blocchi le porte 80 e 443

Il database non si avvia

Se il database non si avvia correttamente:

docker compose logs -f db

In caso di problemi persistenti, puoi ricreare il volume del database (perderai tutti i dati):

docker compose down -v
docker compose up -d

Il comando docker compose down -v elimina tutti i dati del database. Usalo solo se sei sicuro di voler ricominciare da zero.

Python 3 non trovato (macOS / Linux)

Se lo script start.sh restituisce Missing required command: python3, installa Python 3:

brew install python3

Backup e Manutenzione

Backup del Database

I dati del database sono salvati in un volume Docker. Per fare un backup:

docker compose exec db pg_dump -U postgres sagrafacile > backup.sql

Ripristino del Database

Per ripristinare da un backup:

docker compose exec -T db psql -U postgres sagrafacile < backup.sql

Backup della Configurazione

Il file sagrafacile_config.json contiene tutta la configurazione dell’installazione. Conservane una copia in un posto sicuro, specialmente il JWT Secret: perderlo richiede la riconfigurazione completa e il logout forzato di tutti gli utenti.

Prossimi Passi

Dopo aver completato l’installazione:

Last updated on
CloudIntroduzione