operator.yaml

operator.yaml è l’unico file che modifichi. Copialo da scripts/tc-operator/operator.yaml.example, tienilo in modalità 0600, e non metterlo mai in un commit — contiene la tua password SMTP, che è l’unico segreto che vi risiede. Ogni altro segreto viene generato in /etc/trusted-codes/secrets.env.

Obbligatori

home_server: node1.example.com
admin_email: ops@example.com

home_server è l’identità del nodo. Non può essere cambiato su un nodo in esecuzione — vedi Limiti sotto.

Email

smtp:
  host: smtp.resend.com
  port: 465
  user: resend
  pass: <la tua API key>
  sender_name: Your Node
  sender_email: '' # predefinito a noreply@<home_server>

Un solo provider per tutta la posta del nodo. Tieni la porta a 465. Vedi Prima di iniziare per il perché, e per il requisito del dominio verificato, che è l’altra cosa che di solito va storta.

Chi può avere un account

auth:
  registration_mode: invitation_only

Solo invitation_only (il predefinito) e closed sono tuoi da impostare. Puoi solo restringere, mai allentare. La registrazione aperta e organica è autorizzata centralmente attraverso la concessione firmata del nodo; impostare open qui viene ignorato e trattato come invitation_only.

Due domande correlate non vengono impostate in questo file, e vengono impostate invece nell’app di amministrazione sotto Node Settings:

1. Che cosa succede quando uno dei tuoi membri invita qualcuno che non ha un account da nessuna parte — rifiutare, o mandarlo a registrarsi su Trusted Codes. Scegliere di mandarlo invia l’indirizzo email della persona invitata a Trusted Codes. È un doppio cancello: anche il server centrale deve accettare offerte dal tuo nodo, altrimenti l’invito del tuo membro fallisce semplicemente senza alcuna ragione mostrata a lui.
2. Se altri server possano collocare inviti sul tuo nodo per i tuoi membri. Questo è il tuo interruttore di sicurezza in entrata, e può essere impostato su nega da qualsiasi stato.

Sono deliberatamente fuori da questo file, perché ogni reload riscrive i flag di federazione incondizionatamente — un valore impostato qui azzererebbe silenziosamente una decisione presa più tardi.

Flag di federazione

federation: true

federation: true attiva l’intero insieme partecipante — code_lookup, open_link_claim, invitations, groups e multi_account. Qualsiasi chiave per singolo flag sovrascrive la scorciatoia.

Due cose da sapere:

• Un trasporto email è un prerequisito rigido. Senza smtp.host, l’installer forza l’intero insieme a spento e te lo dice.
• Il file di esempio imposta ogni flag esplicitamente a false. Se lo copi senza modificarlo ottieni un nodo con la federazione spenta, anche se un nodo con SMTP configurato per il resto è predefinito su acceso. Impostali deliberatamente.

Che cosa espone ciascuna superficie, e perché due di esse sono state segnalazioni di sicurezza, è coperto nella sezione Server federato. Leggila prima di attivarle.

La discovery WebFinger è sempre attiva. Un nodo deve essere scopribile per federare.

Superfici

Quali superfici web serve questo nodo sotto il tuo dominio. Usa la forma a blocco; la forma inline my: { enabled: true } non viene interpretata.

surfaces:
  admin:
    enabled: true
  my:
    enabled: false
  verify:
    enabled: false
  provider:
    enabled: false
  status:
    enabled: false
  business:
    enabled: false
    # host: verify.example.com   # sovrascrittura del dominio per singola superficie

admin è attiva per impostazione predefinita e non può mai essere fermata — è la superficie di ripristino. Ogni superficie attivata viene compilata sulla macchina e ha bisogno del proprio record DNS A.

Branding

branding:
  product_name: Trusted Codes
  primary_color: '#1a3a5c'
  # logo_url: https://node1.example.com/logo.svg

Il nome, il colore e il logo vengono pubblicati nelle informazioni firmate del nodo e applicati ai contenuti propri del nodo — email, guida, onboarding.

Integrazioni opzionali

Tutto qui è opzionale. Lascia vuota una chiave e quella funzione è semplicemente spenta: il nodo continua a girare, e sia il riepilogo dell’installazione sia tc-operator status mostrano quali integrazioni sono attive e quali no. Niente fallisce silenziosamente. Ottieni queste chiavi da solo, per la tua installazione; Trusted Codes non le vede mai.

Integrazione	Chiavi	Vuoto significa
MaxMind — geografia e punteggio antifrode su accessi e ricerche	integrations.maxmind.account_id, license_key	gli accessi procedono senza punteggio, fail-open
Chat IA	integrations.ai.mistral_api_key oppure gemini_api_key	l’assistente è spento
Metabase — dashboard integrate nell’app di amministrazione	integrations.metabase.site_url, embedding_secret	dashboard non disponibili

Il predefinito di MaxMind vale una seconda occhiata. Per un nodo che dovrebbe bloccare gli accessi quando il punteggio non è disponibile invece di lasciarli passare, esiste un parametro separato da impostare.

Fatturazione e push per il telefono sono solo centrali e non hanno impostazione qui.

Relay push

push_relay_server: app.trusted.codes

Un nome di server di federazione, non un URL. Il tuo nodo possiede i token push dei suoi utenti, ma la credenziale push dell’app condivisa per telefono appartiene a Trusted Codes, quindi il tuo nodo non può parlare direttamente con i servizi push degli app store. Con questo impostato, i push viaggiano come buste di federazione firmate attraverso il relay.

Il relay vede un token, un orario e il nome del tuo server. Mai il contenuto. In questa versione viaggiano solo sollecitazioni silenziose di “svegliati e sincronizza”; il dispositivo allora recupera e rende i dati veri dal tuo nodo. La conseguenza è reale: i tuoi utenti ricevono sveglie di sincronizzazione in background, non testo di notifica spinto dal server. Gli avvisi visibili compaiono quando l’app torna in primo piano e si sincronizza.

Lasciarlo non impostato mantiene gli invii diretti, che funzionano finché la sicurezza push non viene attivata sull’intera piattaforma. Se il push è del tutto fermo non si rompe nulla — i client convergono sulle scansioni in primo piano. Il push non è mai portante in questo prodotto.

Applicare un cambiamento a un nodo in esecuzione

sudo scripts/tc-operator/tc-operator reload --config operator.yaml

Pensalo come portare l’intero nodo a ciò che il file dice adesso. Riverifica SMTP rispetto al provider live prima di applicare qualsiasi cosa, ricompone secrets.env dal file, lascia che Docker ricrei esattamente i container le cui impostazioni sono cambiate, riapplica le impostazioni lato database (flag di federazione, interruttori delle superfici, branding, URL dei portali), rifirma le informazioni pubblicate del nodo, ricarica a caldo il proxy e si autotesta.

I segreti generati — le chiavi JWT, le chiavi di cifratura, l’identità di federazione — non vengono mai ruotati da un reload. Una configurazione invariata è un no-op, quindi è sicuro eseguirlo in qualsiasi momento.

Coperto: smtp, auth, integrations, branding, surfaces, i flag di federazione, push_relay_server, e le sovrascritture del registro e della concessione.

Che cosa reload non fa

• home_server non può essere ricaricato. Cambiarlo è un cambio di identità — DNS, TLS, ammissione al registro. Reload rifiuta e ti indirizza all’installazione.
• admin_email viene applicato solo in parte. Reload aggiorna l’indirizzo di contatto del certificato. Un nuovo account amministratore richiede tc-operator add-admin --email <indirizzo>.
• Una superficie appena attivata non viene compilata. Reload avvisa e ti indirizza a tc-operator service start <superficie>, che la compila e la serve.
• Reload è autoritativo per le superfici. Qualsiasi interruttore improvvisato fatto nell’app di amministrazione dall’ultima riconciliazione viene riportato a ciò che il file dichiara. Install si comporta allo stesso modo.
• Codice nuovo e nuove migrazioni non viaggiano mai per reload. Quello è aggiornamento.