Configurazione dell’istanza

La configurazione dell’istanza definisce origini, segreti, provider opzionali e job pianificati. Questa guida è rivolta all’operatore: conserva i segreti fuori da Git, esponi soltanto gli endpoint previsti e verifica separatamente ogni servizio attivato. Le procedure di manutenzione richiedono di fermare anche job e ingressi che possono scrivere dati.

Configurare origini, segreti e funzionalità dell’istanza

MINDDY_PUBLIC_APP_URL è un’unica origine assoluta senza percorso o slash finale. In pubblico serve HTTPS; localhost e IPv4 privata affidabile possono usare HTTP. MINDDY_PUBLIC_SUPABASE_URL e MINDDY_PUBLIC_SUPABASE_ANON_KEY devono appartenere allo stesso stack; arrivano al browser. SUPABASE_SERVICE_ROLE_KEY resta solo server ed è obbligatoria in produzione, mai in variabili pubbliche o bundle client. URL database serve agli strumenti, non sostituisce configurazione API.

Conservare i segreti

L’installer integra GIT_STATE_SECRET, GIT_TOKEN_ENCRYPTION_SECRET, AI_KEY_ENCRYPTION_SECRET, FEEDBACK_SSO_ENCRYPTION_SECRET, MINDDY_DATA_ROOT_KEY, e CRON_SECRET mancanti. La radice ha esattamente 64 caratteri esadecimali. Mantienila fuori PostgreSQL con copia di recupero protetta. Tutto l’ambiente resta 0600 e fuori Git. Non eseguirlo come shell e non stamparlo. Ripetere installazione non ruota segreti; perderli può rendere dati illeggibili. La rotazione deliberata richiede procedura corretta.

Applicare e controllare una modifica

MINDDY_PUBLIC_SITE_NAME e MINDDY_PUBLIC_CONTACT_EMAIL identificano l’istanza. ADMIN_EMAILS elenca amministratori separati da virgole, con MFA obbligatoria. OAUTH_ISSUER normalmente resta vuoto salvo OAuth pubblicato intenzionalmente su altra origine stabile. Disattiva IA/fatturazione gestite in self-hosted. Servizi opzionali richiedono configurazione completa. Riavvia o ricrea app dopo modifica valori pubblici runtime, senza rebuild OCI. doctor distingue capacità incomplete da errori del nucleo. Prova link account e callback sull’origine prevista.

Configurare feedback e segnalazioni sulla documentazione

Imposta MINDDY_FEEDBACK_KEY su una chiave di integrazione feedback per attivare l’invio di feedback nell’app. Per le segnalazioni sulla documentazione, crea un’integrazione feedback separata nel progetto destinatario, scegli Documentation come obiettivo predefinito e salva la chiave in MINDDY_DOCUMENTATION_FEEDBACK_KEY. Entrambe le chiavi restano sul server. Gli invii usano /api/v1/feedback sull’origine definita da MINDDY_PUBLIC_APP_URL. Riavvia l’applicazione dopo aver modificato questi valori.

Per segnalare un errore da un articolo è necessario aver effettuato l’accesso. Dopo l’accesso, il lettore torna allo stesso articolo con il dialogo di feedback aperto. Il titolo e la descrizione sono inizialmente vuoti. Dopo l’invio, il server aggiunge l’identificativo dell’articolo, la lingua, la revisione e l’URL pubblico; questi dati non sono campi modificabili del modulo. L’integrazione della documentazione collega automaticamente il feedback all’obiettivo selezionato. Senza MINDDY_DOCUMENTATION_FEEDBACK_KEY, il pulsante per segnalare errori è disabilitato e mostra una spiegazione.

Abilitare esplicitamente i provider opzionali

Il nucleo non richiede Stripe, PostHog, un account Cloud o una chiave IA minddy. I servizi esterni aggiungono costi, permessi e destinazioni dei dati: leggi le loro condizioni prima di attivarli. La diagnostica segnala valori mancanti senza scegliere un fallback. Un’istanza self-hosted può usare chiavi personali o endpoint IA locali raggiungibili. Lascia MINDDY_MANAGED_AI e MINDDY_MANAGED_BILLING disattivati; una sola chiave OpenRouter non seleziona l’edizione Cloud.

Configurare i provider completi

L’email dell’applicazione richiede EMAIL_PROVIDER=resend, RESEND_API_KEY, FEEDBACK_EMAIL_FROM e INVITATION_EMAIL_FROM. console non è consentito in produzione; SMTP Auth si configura separatamente. Web Push richiede la coppia VAPID e VAPID_SUBJECT; gli abbonamenti dipendono da quella coppia. Analytics richiede chiave e host PostHog; il tracciamento degli errori richiede MINDDY_PUBLIC_ERROR_TRACKING=1. L’installer propone application-email e web-push, ma le credenziali esterne devono essere fornite dall’operatore. Non usare mittenti minddy o credenziali delle release native su altre istanze.

Collegare Git ed esecuzione del codice

Sono supportati GitHub.com e GitLab.com, non GitHub Enterprise Server o GitLab autogestito. Le connessioni degli utenti possono usare il relay gestito; puoi escluderlo con --no-forge-relay o MINDDY_FORGE_RELAY=0 e configurare app proprie. Le connessioni esistenti mantengono il proprio canale fino alla riconnessione. Numo non esegue codice, quindi il server di riferimento non richiede alcun runner di codice né sandbox, e nessun servizio riceve il socket Docker. Le impostazioni lasciate da una release precedente, come AGENT_EXECUTION_BACKEND, AGENT_RUNNER_URL, AGENT_RUNNER_SECRET, AGENT_CONTROL_ORIGIN e le credenziali di Vercel Sandbox, vengono ignorate; rimuovile dall’ambiente protetto.

Esporre origini e gestire i job pianificati

Un servizio pubblico richiede un proxy TLS e il redirect da HTTP a HTTPS. Le origini minddy e Supabase, i redirect Auth, i callback OAuth e gli header devono concordare. Non esporre PostgreSQL, Studio o porte interne. Nel profilo full il server usa http://kong:8000 internamente, mentre browser e link mantengono l’origine pubblica di Supabase. HTTP privato richiede localhost o una rete IPv4 privata affidabile, senza inoltro delle porte del router.

Fornire pianificazione autenticata

I profili Compose di riferimento avviano lo scheduler e l’installer genera CRON_SECRET. Un deployment personalizzato dai sorgenti deve fornire uno scheduler HTTP equivalente. Ogni richiesta invia Authorization: Bearer <CRON_SECRET>; un valore vuoto o errato restituisce 401. Non registrare questo header. Gli orari elencati sotto sono in UTC e appartengono a questa release. Usa le route della release installata, perché possono cambiare.

Rispetto allo scheduler di v0.11.0, questa release aggiunge numo-turns, forge-relay-maintenance, page-materialization e issue-index e non chiama più /api/cron/agent-drain né /api/cron/automations, rimossi insieme al lavoro sul codice di Numo e alle automazioni di progetto. Uno scheduler personalizzato copiato da v0.11.0 va aggiornato secondo questa tabella.

Fermare i job in manutenzione

Prima di un backup o di una migrazione, ferma scheduler, applicazione, worker e API pubblica. Fermare soltanto il server web lascia possibili scritture dirette. Verifica in manutenzione con ingressi e job chiusi, poi riapri solo dopo i controlli su database, Auth, Storage e applicazione. Se un job non parte, verifica in privato scheduler, origine e segreto. Le routine richiedono il server, non un desktop aperto.