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 

Modalità di Installazione

SagraFacile supporta due modalità di accesso, che scegli durante la configurazione iniziale:

Prerequisiti

Software Richiesto

Requisiti Hardware (Consigliati)

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

Requisiti di Rete (solo modalità dominio pubblico)

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

Installazione

start.bat

--- Installation Mode ---
How will you access SagraFacile?
  1. Public domain with HTTPS  (requires a domain managed on Cloudflare)
  2. Local network only / HTTP (no domain or Cloudflare needed)

--- Local Network Configuration ---
Enter this server's local IP address [192.168.1.10]:

chmod +x *.sh

./start.sh

--- Installation Mode ---
How will you access SagraFacile?
  1. Public domain with HTTPS  (requires a domain managed on Cloudflare)
  2. Local network only / HTTP (no domain or Cloudflare needed)

--- Local Network Configuration ---
Enter this server's local IP address [192.168.1.10]:

Struttura dei File

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

• sagrafacile
  • docker-compose.yml
  • Caddyfile
  • .env
  • sagrafacile_config.json
  • start.bat
  • start.sh
  • stop.bat
  • stop.sh
  • update.bat
  • update.sh

Accesso a SagraFacile

Una volta che i servizi sono attivi, apri il browser su qualsiasi dispositivo connesso alla rete e naviga a:

http://192.168.1.10

https://tuo.dominio.com

Usa le credenziali configurate durante l’installazione per effettuare il login.

Gestione dei Servizi

Avviare i Servizi

Esegui start.* dalla cartella di SagraFacile:

start.bat

./start.sh

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

./stop.sh

Aggiornare i Servizi

Per aggiornare SagraFacile a una nuova versione:

update.bat

./update.sh

Riconfigurare

Per modificare qualsiasi impostazione (modalità, 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

I dispositivi non riescono a connettersi

Il certificato SSL non viene ottenuto (solo modalità dominio)

Controlla i log di Caddy per maggiori dettagli:

docker compose logs -f caddy

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

Impossibile accedere — credenziali non valide o account admin non creato

Se dopo l’installazione il login non funziona, le cause più comuni sono:

• Le credenziali inserite durante il setup sono quelle di accesso. L’email e la password che hai configurato in start.* sono il tuo account amministratore. Se non ricordi quali hai usato, aprila cartella di installazione e controlla il file sagrafacile_config.json — i campi INITIAL_ADMIN_EMAIL e INITIAL_ADMIN_PASSWORD contengono le credenziali configurate.
• La password è troppo semplice. L’applicazione richiede una password con almeno una lettera maiuscola, un numero e un simbolo (es. MiaPass1!). Se hai inserito una password semplice, l’account potrebbe non essere stato creato.
• Il setup è stato interrotto prima dei prompt delle credenziali. In questo caso il database è stato inizializzato senza un account admin.

Soluzione: reset completo e nuovo setup

docker compose down
docker volume rm sagrafacile_sagrafacile_db_data
.\start.bat

docker compose down
docker volume rm sagrafacile_sagrafacile_db_data
./start.sh

Lo script start.* rileverà la configurazione esistente e chiederà se usarla o riconfigurarla. Scegli 2 - Re-configure per impostare nuove credenziali, oppure premi Invio per usare la configurazione salvata. Al successivo avvio, le credenziali verranno ricreate nel database pulito.

Python 3 non trovato (macOS / Linux)

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

brew install python3

sudo apt-get update && sudo apt-get install -y python3

sudo dnf install -y python3

Errore di migrazione database all’aggiornamento a v2.6.0

Se dopo aver aggiornato all’ultima versione l’API non si avvia e nei log compare un errore simile a:

23503: insert or update on table "AdAreaAssignments" violates foreign key constraint
"FK_AdAreaAssignments_OrganizationMediaAssets_MediaAssetId"

si tratta di un problema di dati: esistono assegnazioni pubblicitarie (AdAreaAssignments) che puntano a file multimediali eliminati in precedenza. La migrazione non riesce ad aggiungere il vincolo di integrità referenziale finché questi record orfani sono presenti.

Soluzione: accedi al database e rimuovi i record orfani, poi riavvia i servizi.

# Connettiti al database
docker compose exec db psql -U <db_user> <db_name>
 
# Rimuovi i record orfani (nessuna perdita di dati operativi)
DELETE FROM "AdAreaAssignments"
WHERE "AdMediaItemId" IS NOT NULL
  AND "AdMediaItemId" NOT IN (SELECT "Id" FROM "AdMediaItems");
 
# Esci da psql
\q

# Riavvia i servizi — la migrazione ora andrà a buon fine
docker compose restart api

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:

• Consulta la guida Organizzazioni e Aree per configurare la struttura del tuo evento
• Leggi la guida Utenti e Ruoli per capire come gestire il team
• Segui la Guida Amministratore per la configurazione completa