Panoramica

La configurazione di Snapp è centralizzata in un singolo file settings.yaml.

Le versioni precedenti dividevano la configurazione tra variabili d’ambiente, stato nel database e default parzialmente hard-coded. Questo rendeva il comportamento opaco, difficile da interpretare e soggetto a errori. Il modello attuale collassa intenzionalmente tutta la configurazione runtime in un unico documento validato.

settings.yaml è ora:

  • L’unica fonte di verità
  • Caricato all’avvio
  • Ricaricato a caldo a runtime
  • Validato in modo rigoroso a ogni modifica
  • Supportato da default e fallback espliciti

Il file viene monitorato tramite i metadati del filesystem (mtime). Ogni modifica valida viene applicata live senza riavviare il processo o il container.

Posizione del file di configurazione

Per default, Snapp legge /app/config/settings.yaml.

Nei deployment Docker, questo file è tipicamente montato da: ./config/settings.yaml

Se il file non esiste, Snapp:

  1. Genera una configurazione minima di fallback
  2. Si avvia normalmente
  3. Persiste il file generato su disco

Modello di validazione e fallback

La configurazione viene parsata tramite uno schema rigoroso (Valibot).

Comportamento al caricamento:

  • I campi mancanti vengono riempiti usando i default dello schema
  • I valori non validi rifiutano l’aggiornamento
  • L’ultima configurazione valida resta attiva
  • Gli errori vengono loggati, mai ignorati silenziosamente

Questo vale sia all’avvio sia durante i reload live.

Configurazione minima

Questa è la configurazione valida più piccola.

appname: Snapp

admin:
  - email: admin@example.org
    username: admin

hosts:
  - origin: https://example.org

Questa configurazione è sufficiente per:

  • Inizializzare un account amministratore
  • Consentire l’accesso da una singola origine pubblica
  • Eseguire Snapp senza integrazioni opzionali

Esempio di configurazione completa

L’esempio seguente rappresenta tutti i campi supportati.

appname: Snapp

admin:
  - email: admin@example.org
    username: admin

hosts:
  - origin: https://auth.example.org
    options:
      customRedirect: /dashboard
      disable:
        homepage: false
        limits: true
        lowerCaseFallback: true
        signup: false
        twoFactor: true
      limits:
        maxSnappPerUser: 0
        requestsPerDay: 100
        requestsPerMinute: 14400
    thirdparty:
      umami:
        url: https://metrics.example.org
        websiteId: 00000000-0000-0000-0000-000000000000
      vtapi:
        apikey: REDACTED

  - origin: https://example.org
    options:
      customRedirect: /dashboard
      disable:
        homepage: false
        limits: true
        signup: false
        twoFactor: true

smtp:
  enabled: true
  from: no-reply@example.org
  host: smtp.example.org
  port: 465
  secure: true
  user: no-reply@example.org
  pass: REDACTED

Campi di primo livello

appname

appname: Snapp
  • Nome visualizzato dell’applicazione
  • Usato nella UI, nei flussi di autenticazione e nei template email
  • Opzionale
  • Default: Snapp

Bootstrap amministratori

admin:
  - email: admin@example.org
    username: admin

Le voci admin vengono riconciliate all’avvio.

Comportamento:

  • All’avvio, Snapp verifica che ogni admin configurato esista
  • Se un admin viene eliminato dalla UI, viene ricreato al prossimo avvio
  • Le password vengono generate una sola volta e stampate nei log
  • Le password non vengono mai rigenerate automaticamente
  • Rimuovere questa sezione non rimuove gli admin esistenti

Campi:

  • email Obbligatorio, indirizzo email validato

  • username Obbligatorio, lunghezza minima applicata

Hosts

L’array hosts definisce tutte le origini pubbliche consentite e il loro comportamento runtime.

Ogni voce rappresenta un tenant logico.

hosts:
  - origin: https://example.org

origin

  • Origine completamente qualificata (protocollo richiesto)

  • Usata per:

    • Validazione CORS
    • Validazione dei redirect
    • Risoluzione dei link pubblici
    • Base URL per l’autenticazione

  • Una versione “slugificata” dell’origine viene usata come ID organizzazione nel database

options

Configurazione comportamentale per host.

customRedirect

customRedirect: /dashboard
  • Percorso di redirect di default quando la homepage è disabilitata
  • Applicato dopo l’autenticazione
  • Default: /dashboard

disable

Interruttori a livello di funzionalità.

disable:
  homepage: false
  limits: true
  lowerCaseFallback: true
  signup: false
  twoFactor: true

  • homepage Disabilita la landing page pubblica

  • limits Disabilita completamente rate limiting e limiti di utilizzo

  • lowerCaseFallback Disabilita il fallback automatico in lowercase per gli shortcode

  • signup Disabilita la registrazione pubblica degli utenti

  • twoFactor Disabilita l’obbligo e la configurazione del 2FA

Questi flag influenzano direttamente autenticazione, routing e rate limiting.

limits

limits:
  maxSnappPerUser: 0
  requestsPerDay: 100
  requestsPerMinute: 14400

  • maxSnappPerUser

    • -1 o valori negativi = illimitato

  • requestsPerDay

    • Per utente, per host

  • requestsPerMinute

    • Protezione dai burst

I limiti sono applicati solo se disable.limits è false.

Internamente, i limiti influenzano sia il throttling delle API key sia le richieste autenticate.

Integrazioni di terze parti

Analytics Umami

thirdparty:
  umami:
    url: https://metrics.example.org
    websiteId: 00000000-0000-0000-0000-000000000000

  • Abilita analytics server-side

  • Usato per:

    • Logging delle visite
    • Metriche aggregate

  • Opzionale

  • Disabilitato se omesso

API VirusTotal

thirdparty:
  vtapi:
    apikey: REDACTED

  • Abilita controlli di reputazione sugli URL

  • Usato durante:

    • Creazione dei link
    • Audit di sicurezza

  • Opzionale

  • Fortemente consigliato per istanze pubbliche

Configurazione SMTP

SMTP è usato per le email legate all’autenticazione.

smtp:
  enabled: true
  from: no-reply@example.org
  host: smtp.example.org
  port: 465
  secure: true
  user: no-reply@example.org
  pass: REDACTED

Campi:

  • enabled Quando false, le email vengono renderizzate nei log

  • from Indirizzo mittente

  • host Hostname del server SMTP

  • port Solitamente 465 (TLS implicito) o 587

  • securetrue per TLS implicito

  • user

  • pass

Le credenziali SMTP non vengono mai memorizzate altrove.

Comportamento runtime

  • La configurazione viene ricaricata a ogni modifica del file
  • Gli aggiornamenti non validi vengono rifiutati
  • L’ultima configurazione valida resta attiva
  • I client di autenticazione vengono aggiornati per host quando cambiano le impostazioni rilevanti
  • Nessun riavvio richiesto

Note

  • settings.yaml è stateful

  • Effettua il backup insieme a:

    • volume PostgreSQL
    • asset caricati (avatars, logos)

  • I segreti sono memorizzati in chiaro

    • Proteggi il file di conseguenza

  • Le versioni beta possono introdurre nuovi campi o default