Guida per l’amministratore di Goooy

Tutto ciò di cui un amministratore ha bisogno per eseguire, mettere in sicurezza e gestire Goooy: la tua alternativa self-hosted a Microsoft Exchange / Office 365.

Goooy è una suite groupware completa che ospiti tu stesso: posta, calendario, contatti, attività, note, chat, file, videoriunioni, office collaborativo e una console di amministrazione, tutto da un’unica applicazione, un unico modello di dati e un unico Helm chart. Sei tu il proprietario dei server, dei dati e delle chiavi.

Questa guida è rivolta a chi gestisce Goooy. Per le fondamenta tecniche della piattaforma (l’architettura, il deployment con Helm o Docker Compose e la configurazione essenziale), consulta la Guida per sviluppatori. Per la visione delle app dal punto di vista dell’utente finale, consulta la Guida utente. Per i dettagli tecnici approfonditi, la cartella docs/ contiene riferimenti dedicati (architettura, sicurezza, server di posta, tenancy, deployment, migrazione e i protocolli client nativi).

Indice

• La console di amministrazione
• Organizzazioni, domini e utenti
• Autenticazione e policy di accesso
• Il server di posta
• Client nativi e gestione dei dispositivi
• Migrazione da un altro sistema
• Multi-tenancy e isolamento
• Sicurezza e conformità
• Backup e operazioni
• Registrazione self-service e il tuo sito di marketing

La console di amministrazione

Accedi come amministratore e ottieni un’area Admin protetta da RBAC (la superficie REST è /api/v1/admin, riservata a SYSADMIN / ORGADMIN e con ambito per organizzazione). Da essa puoi:

• Gestire organizzazioni, domini, utenti e gruppi (creare, modificare, eliminare).
• Visualizzare una dashboard di statistiche sull’utilizzo della piattaforma/organizzazione.
• Gestire il Mobile Device Management: elencare i dispositivi registrati e richiedere il wipe remoto.
• Integrare una directory: importare utenti in blocco e sincronizzare da LDAP.
• Configurare l’SSO per organizzazione e la policy di sicurezza (obbligo di 2FA, imposizione dell’SSO).
• Verificare la proprietà del dominio tramite record DNS TXT.
• Eseguire migrazioni da altri sistemi di posta (Admin ▸ Migrazioni).

Organizzazioni, domini e utenti

La spina dorsale della tenancy di Goooy è Organization → Domain → User. Ogni utente possiede una casella di posta con un albero di cartelle tipizzato (posta, calendario, contatti, attività, note, file), così un unico modello di archiviazione e permessi sostiene ogni app. L’eliminazione di un’organizzazione, di un utente o di una casella di posta si propaga in modo pulito a tutto ciò che ne dipende.

Ruoli (RBAC)

Le azioni di ORGADMIN sono automaticamente limitate al loro orgId; un ORGADMIN non può creare organizzazioni né concedere SYSADMIN. Ogni query multi-tenant filtra in base all’organizzazione del chiamante, così i tenant non vedono mai i dati degli altri.

Aggiungere utenti

Crea gli utenti singolarmente nella console, importali in blocco o sincronizzali da LDAP con ldapts. Ogni nuovo utente viene automaticamente fornito di una casella di posta e dell’albero di cartelle predefinito. Le password seguono la tua policy (vedi sotto).

Verifica della proprietà del dominio

Prima che un dominio gestisca posta reale, un amministratore può dimostrarne il controllo nello stesso modo di Google Workspace e Microsoft 365:

1. La console mostra un record TXT da pubblicare (_goooy-verify.<domain> con un valore di token stabile).
2. Pubblicalo nel tuo DNS.
3. Fai clic su Verifica ora. Goooy esegue un lookup DNS in tempo reale e contrassegna il dominio come verificato.

Questo è limitato all’organizzazione e sottoposto ad audit; un ORGADMIN può verificare solo i domini della propria organizzazione.

Autenticazione e policy di accesso

Goooy supporta l’intera gamma di controlli di accesso moderni. I valori predefiniti sono sicuri; irrigidiscili per organizzazione secondo necessità.

Password

• Con hash tramite bcrypt (cost 12), gli stessi hash che verifica Dovecot, così c’è un unico store di credenziali per la webmail e per IMAP/POP3 nativo.
• Una policy sulle password viene applicata a ogni impostazione/modifica/reimpostazione/registrazione: una lunghezza minima (PASSWORD_MIN_LENGTH, predefinita 10) e un controllo facoltativo delle violazioni tramite Have I Been Pwned (k-anonimato: dal server esce solo un prefisso SHA-1 e il controllo fallisce in modo aperto, così un’interruzione di HIBP non blocca mai una modifica della password).
• La reimpostazione self-service della password è sicura contro l’enumerazione e revoca tutte le altre sessioni al momento dell’uso.

Autenticazione a più fattori

• Codici di autenticazione TOTP con codici di recupero monouso, più passkey FIDO2/WebAuthn (con rilevamento della clonazione).
• Imposta Organization.requireMfa per rendere obbligatoria la 2FA per un’organizzazione. Gli utenti vengono guidati nella registrazione e bloccati dall’app finché non la completano.

Difesa da brute-force e appropriazione degli account

• Due livelli di throttling: un rate limit per IP sugli endpoint di login/MFA e un blocco per account (dopo una soglia di tentativi falliti l’account si blocca per una finestra di tempo che cresce in modo esponenziale) che sconfigge il credential-stuffing distribuito.
• Audit degli accessi: ogni tentativo viene registrato (IP, user-agent, esito) e gli utenti possono vedere i propri accessi recenti in Impostazioni → Sicurezza.
• Avvisi da nuovo dispositivo: la prima volta che un dispositivo effettua l’accesso, l’account riceve un’email di “nuovo accesso”; anche le modifiche a password e MFA notificano l’utente (subordinate a SECURITY_EMAILS_ENABLED).

Single sign-on (OIDC per organizzazione)

Configura una connessione OIDC generica per organizzazione (flusso Authorization Code). L’organizzazione viene risolta dal dominio email dell’utente (home-realm discovery), gli utenti vengono forniti just-in-time se il loro dominio è ospitato e il client secret è a sola scrittura (sigillato a riposo, mai restituito).

Puoi imporre l’SSO per un’organizzazione (ssoEnforced) per disabilitare completamente il login con password, con due protezioni che impediscono di rimanere chiusi fuori: ha effetto solo finché esiste una connessione SSO utilizzabile, e gli account SYSADMIN mantengono sempre il login con password come misura di emergenza (break-glass).

Consulta Onboarding self-service e autenticazione esterna per l’API di autenticazione completa, e Sicurezza per il riferimento approfondito.

Il server di posta

Per impostazione predefinita Goooy è autonomo: accetta la posta in entrata sui propri listener SMTP (2525) e LMTP (2526), inoltra la posta in uscita tramite nodemailer, valuta lo spam con un’euristica integrata basata su regole e consegna localmente tra gli utenti ospitati, così la posta interna funziona senza alcuna infrastruttura esterna.

Per la posta internet reale, abilita lo stack Postfix + Dovecot + Rspamd e l’API diventa l’hub di consegna di un server di posta completo:

helm upgrade goooy ./deploy/helm/goooy --set mail.enabled=true

Internet ─SMTP:25─▶ Postfix ──milter──▶ Rspamd ──LMTP──▶ api ─┬─▶ Postgres (web UI; spam→Junk)
 clients ─587/465─▶  (MTA, SASL)        (scan+DKIM)           └─▶ Dovecot ─▶ Maildir (IMAP/POP3)

• Postfix accetta la posta per i tuoi domini ospitati (cercati in tempo reale in Postgres), la analizza attraverso il milter Rspamd (SPF/DKIM/DMARC + spam scoring) e la consegna all’API tramite LMTP.
• L’API scrive il messaggio in Postgres (lo store della webmail, archiviando nella cartella Indesiderata lo spam segnalato da Rspamd) e lo rispecchia in Dovecot affinché i client IMAP/POP3 nativi lo vedano.
• La posta in uscita viene reinstradata tramite Postfix, firmata DKIM da Rspamd.

L’anti-phishing è integrato: i risultati dell’autenticazione del mittente in entrata vengono memorizzati per ogni messaggio; un banner di mittente esterno segnala la posta proveniente dall’esterno dei tuoi domini; gli spoofing del proprio dominio non autenticati vengono archiviati in Indesiderata con un forte avviso; le azioni “Segnala” / “Non è spam” degli utenti addestrano il filtro Bayesiano di Rspamd; e il lettore avvisa in caso di link ingannevoli, host omografi/punycode e impersonificazione del nome visualizzato, con i contenuti remoti bloccati per impostazione predefinita e gestiti tramite proxy.

Link sicuri e sandboxing degli allegati. Due ulteriori difese per la posta in arrivo, attivabili per organizzazione in Admin ▸ Sicurezza della posta (entrambe disattivate per impostazione predefinita):

• I link sicuri riscrivono ogni link della posta esterna in arrivo e ricontrollano la destinazione al momento del clic: gli URL in blocklist ricevono una pagina di blocco, quelli sospetti (host con IP letterale, credenziali incorporate, sosia punycode) una pagina di avviso, quelli puliti vengono reindirizzati direttamente: ogni clic è tracciato. Le copie inviate, la posta interna e i corpi firmati o cifrati restano intatti.
• Il sandboxing degli allegati detona staticamente gli allegati in arrivo, in aggiunta alla scansione antivirus sempre attiva: eseguibili rilevati dal contenuto, progetti macro di Office, archivi protetti da password o annidati, e HTML/SVG con script. La posta dannosa viene archiviata in Posta indesiderata e ogni allegato segnalato viene messo in quarantena (download bloccato) finché un amministratore dell’organizzazione non lo rilascia.

Attenzione operativa: non mettere mai permit_mynetworks su un listener SMTP esposto a internet. Questo crea un open relay. Le configurazioni fornite separano la porta pubblica :25 da una porta di submission solo interna proprio per questo motivo. Tutti i dettagli e i limiti sono in Server di posta e deploy/mail/README.md.

Client nativi e gestione dei dispositivi

Goooy parla i protocolli standard, così i tuoi utenti mantengono le app che già hanno. Tutti sono montati sui rispettivi root ben noti e usano HTTP Basic (email + password) dove il protocollo lo prevede:

App Outlook per dispositivi mobili: l’app Outlook per iOS/Android necessita di un EAS in stile OAuth che Goooy non offre; consiglia agli utenti iPhone/iPad di usare invece l’app Apple Mail integrata.

Mobile Device Management. I dispositivi che si registrano tramite ActiveSync vengono tracciati. Dalla console MDM puoi elencare i dispositivi registrati e richiedere un wipe remoto. Il dispositivo viene contrassegnato e cancellato alla sincronizzazione successiva.

L’helpdesk

Un helpdesk è uno strato di flusso di lavoro sopra una casella condivisa, non un sistema separato. Crea prima la casella condivisa, condividila con gli operatori, poi attivaci sopra l’helpdesk da Amministrazione ▸ Helpdesk.

• Gli operatori sono esattamente le persone con cui la casella è condivisa. Chi ha solo lettura può aprire i ticket, ma non assegnarli, rispondere o cambiarne lo stato.
• Le impostazioni della coda contengono il prefisso della chiave (TCK), l’orario di lavoro, gli obiettivi di prima risposta e risoluzione in minuti lavorativi, il periodo di chiusura automatica e la conferma inviata a un nuovo mittente.
• Le risposte predefinite valgono per una coda o per tutta l’organizzazione.
• La classificazione con IA è opzionale per coda: propone priorità ed etichette e non invia mai nulla da sola.

La consegna della posta non cambia: ogni messaggio arriva sempre nella posta in arrivo della casella e resta visibile via IMAP, ActiveSync, MAPI e JMAP. Se disattivi l’helpdesk, la casella e tutta la sua posta restano esattamente come erano.

Autenticazione della posta e rapporti

Pubblicare SPF, DKIM e DMARC è il primo passo; sapere se funzionano è il secondo. Fai puntare l’indirizzo rua= del record DMARC a una casella del dominio e Goooy analizza ogni rapporto aggregato appena viene consegnato.

Amministrazione ▸ Autenticazione della posta mostra poi, per dominio: il tasso di conformità, l’allineamento di SPF e DKIM e le sorgenti di invio che falliscono, che è il modo per distinguere un mittente legittimo dimenticato da qualcuno che ti sta falsificando. I rapporti TLS di SMTP (TLS-RPT) arrivano allo stesso modo e mettono in luce le connessioni fallite o declassate.

Goooy può anche ospitare una policy MTA-STS per dominio su /.well-known/mta-sts.txt, così gli altri provider si rifiutano di consegnare la tua posta su una connessione non cifrata.

Provisioning con SCIM e LDAP

Tre modi per tenere gli account allineati alla tua directory:

• SCIM 2.0 su /scim/v2, autenticato con un token bearer per organizzazione. Il tuo provider di identità crea, aggiorna e disattiva utenti e gruppi man mano che le persone arrivano, cambiano ruolo e se ne vanno.
• Sincronizzazione LDAP / Active Directory, che preleva utenti e gruppi in modo programmato.
• Import massivo via CSV per un caricamento una tantum.

Combinali con l’SSO per organizzazione, così disattivare qualcuno al centro gli toglie l’accesso ovunque, client nativi compresi.

Migrazione da un altro sistema

Il Goooy Mover trasferisce i dati di un’azienda esistente in Goooy da un server IMAP live o da file di export caricati: un amministratore mappa ogni casella di posta di origine su un utente Goooy (gli utenti mancanti vengono forniti automaticamente), fa clic su avvia e il trasferimento avviene in background con un tracker di stato in tempo reale per utente. L’interfaccia di amministrazione è Admin ▸ Migrazioni.

Cosa preserva e garantisce:

• Gerarchia delle cartelle: le cartelle note (Posta in arrivo, Inviata, Cestino, Indesiderata, Archivio) vengono mappate sui rispettivi ruoli in Goooy; le cartelle più profonde vengono ricreate come sottocartelle.
• Date e stato: le date di ricezione originali e lo stato letto/contrassegnato, così una casella di posta migrata appare come l’originale.
• Riprendibile e idempotente: registra checkpoint di avanzamento, così l’arresto dell’API a metà batch riprende da dove si era interrotto, e una nuova esecuzione non crea mai duplicati (deduplicazione tramite Message-ID, o tramite un UID per calendario/contatti).

Il percorso a server live funziona con Gmail, Microsoft 365, Dovecot, Zimbra e la maggior parte dei server IMAP (usa una app-password dove il provider ne richiede una: la procedura guidata offre profili di connessione con un clic per i provider più comuni). Il percorso di caricamento file accetta Outlook .pst (posta + calendario + contatti), .mbox (posta, incluso un export di Google Takeout: il modo più semplice per uscire da un account Gmail personale), .ics (calendario) e .vcf (contatti), con il formato rilevato automaticamente dal contenuto del file. Il flusso è Origine → Account→ utenti (con un Test delle credenziali per riga, o un caricamento per file) → Esecuzione → Dashboard in tempo reale con retry per riga e pausa/annullamento del batch. Tutte le modifiche sono sottoposte ad audit. Tutti i dettagli e la roadmap (CalDAV/CardDAV, Microsoft 365 Graph, Gmail API, tenant-to-tenant) sono in Migrazione.

Multi-tenancy e isolamento

Per impostazione predefinita Goooy è logicamente multi-tenant: ogni query è limitata da orgId e protetta da RBAC, con tutti i tenant che condividono un unico database. Per requisiti più stringenti, una modalità opt-in di isolamento forte assegna a ogni tenant un proprio schema PostgreSQL o un proprio database:

TENANT_ISOLATION = shared (default) | schema | database

Un catalogo del control plane risolve la connessione corretta per ogni richiesta (req.db), così l’impostazione predefinita con database condiviso resta completamente invariata se non attivi l’opzione. Questo ti permette di offrire residenza dei dati per tenant o isolamento contrattuale senza gestire deployment separati. Vedi Tenancy.

Sicurezza e conformità

Una checklist sintetica. Il riferimento autorevole è Sicurezza.

• Trasporto. Il TLS termina all’Ingress (facoltativamente automatizzato con cert-manager). Il TLS verso gli store di supporto è pilotato dall’URL e non richiede modifiche al codice: ?sslmode=require su DATABASE_URL, rediss:// per Redis, endpoint S3 https://.

• Header. Helmet sull’API; nginx imposta una CSP rigorosa, X-Frame-Options: SAMEORIGIN, Referrer-Policy e una Permissions-Policy che limita camera/microfono/display-capture a self. Il CORS è limitato a PUBLIC_WEB_URL (i percorsi di protocollo nativi sono intenzionalmente esenti, non “correggerlo”).

• Sicurezza email end-to-end (S/MIME). Ogni utente può avere un’identità X.509 autofirmata per firmare/verificare (RSA-SHA256) e cifrare/decifrare (ibrido RSA-OAEP + AES-256-GCM, multi-destinatario); la chiave privata è sigillata a riposo e non viene mai restituita in chiaro.

• Rendering delle email. La posta HTML viene sanificata con DOMPurify e vincolata dalla CSP di nginx. Mantieni entrambi.

• Secret a riposo. Le chiavi S/MIME, i secret client SSO e le credenziali di migrazione sono sigillati con AES-256-GCM usando JWT_SECRET. Fornisci il tuo Secret; ruota JWT_SECRET con cautela (invalida i valori sigillati).

• I container vengono eseguiti come non-root sotto un security context restrittivo.

• Sovranità dei dati. Goooy è self-hosted da un capo all’altro. Scegli tu la regione e il provider per ogni store. Vedi Sovranità dei dati.

• Conservazione. Le policy per organizzazione fanno scadere posta, file e messaggi secondo il calendario che imposti. La scansione gira in background ed è tracciata.

• Blocco legale. Un blocco su una persona ne conserva i dati, prevale sulla conservazione finché non viene revocato ed esporta tutto in JSON per la revisione.

• Prevenzione della perdita di dati. Analisi su tutta l’organizzazione tra posta, chat e file secondo i criteri che configuri.

Licenza: AGPL-3.0-or-later.

Backup e operazioni

• Cosa sottoporre a backup: PostgreSQL (il sistema di riferimento) e il tuo bucket S3 (i blob di file e allegati). Redis è effimero e non necessita di backup. Il chart può eseguire un CronJob pg_dump notturno (backup.enabled=true).
• Probe di salute: l’API espone /healthz (liveness) e /readyz (readiness basata sul DB) per Kubernetes.
• Scalabilità: l’API è stateless (autenticazione JWT) e distribuisce il tempo reale tramite Redis pub/sub, quindi scala orizzontalmente. Abilita l’HPA (autoscaling.enabled=true, richiede metrics-server) e un PodDisruptionBudget per rollout sicuri.
• Osservabilità: log JSON strutturati (pino).
• Modifiche allo schema: il container dell’API esegue prisma migrate deploy all’avvio, così le migrazioni committate vengono applicate automaticamente al rollout.
• Non terminare le porte di ingest (2525/2526) per “liberarle” in un ambiente in esecuzione. È così che arriva la posta in entrata.

Registrazione self-service e il tuo sito di marketing

Goooy può eseguire un flusso pubblico di registrazione self-service affinché i clienti creino la propria organizzazione. È disabilitato per impostazione predefinita. Imposta SELF_SIGNUP_ENABLED=true per attivarlo. L’endpoint crea in modo atomico un’Organization, il suo primo Domain e un utente ORGADMIN (mai SYSADMIN), e restituisce una sessione attiva. È soggetto a rate limit per IP come barriera contro gli abusi.

L’app web inclusa fornisce già una pagina pubblica /signup che pilota questo flusso in same-origin, così non devi crearla tu. E un sito di marketing statico in Astro (apps/marketing) è incluso come vetrina pubblica. Abilitalo sul suo host dedicato:

helm upgrade goooy ./deploy/helm/goooy \
  --set marketing.enabled=true \
  --set marketing.host=www.example.com

Il suo CTA “Inizia ora” rimanda alla pagina /signup dell’app. L’API completa di autenticazione esterna (login, MFA, SSO, sessioni, verifica del dominio), tutto ciò che ti servirebbe per creare invece il tuo front di registrazione, è documentata in Onboarding self-service e autenticazione esterna.

Inizia ora

• Sei nuovo qui? Leggi la Guida utente per la visione di ogni app dal punto di vista dell’utente finale.
• Stai distribuendo o integrando la piattaforma? La Guida per sviluppatori copre l’architettura, il deployment con Helm/Docker Compose e la configurazione.
• Sfoglia le pagine panoramica delle funzionalità, sicurezza e conformità e self-hosting.
• Il riferimento tecnico completo (architettura, modello di dati, server di posta, tenancy, deployment, migrazione e i protocolli client nativi) è incluso nel codice sorgente del prodotto.