operator.yaml

operator.yaml ist die einzige Datei, die du bearbeitest. Kopiere sie von scripts/tc-operator/operator.yaml.example, behalte den Modus 0600, und committe sie nie — sie enthält dein SMTP-Passwort, das einzige Geheimnis, das in ihr steht. Jedes andere Geheimnis wird in /etc/trusted-codes/secrets.env erzeugt.

Erforderlich

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

home_server ist die Identität des Knotens. Sie kann auf einem laufenden Knoten nicht geändert werden — siehe Grenzen unten.

E-Mail

smtp:
  host: smtp.resend.com
  port: 465
  user: resend
  pass: <dein API-Schlüssel>
  sender_name: Your Node
  sender_email: '' # Standard ist noreply@<home_server>

Ein Provider für die gesamte Post des Knotens. Halte den Port bei 465. Siehe Bevor du beginnst für den Grund, und für die Anforderung der verifizierten Domain, das andere, was meist schiefgeht.

Wer ein Konto halten darf

auth:
  registration_mode: invitation_only

Nur invitation_only (die Voreinstellung) und closed sind deine, um sie zu setzen. Du darfst verschärfen, nie lockern. Offene, organische Registrierung wird zentral durch die signierte Lizenz des Knotens autorisiert; setzt du hier open, wird das ignoriert und als invitation_only behandelt.

Zwei verwandte Fragen werden nicht in dieser Datei gesetzt, sondern stattdessen in der Admin-App unter Node Settings:

1. Was passiert, wenn eines deiner Mitglieder jemanden einlädt, der nirgendwo ein Konto hat — ablehnen, oder die Person zur Registrierung an Trusted Codes schicken. Entscheidest du dich, sie zu schicken, geht die E-Mail-Adresse der eingeladenen Person an Trusted Codes. Das ist ein doppeltes Tor: Der zentrale Server muss Angebote von deinem Knoten ebenfalls akzeptieren, sonst schlägt die Einladung deines Mitglieds einfach fehl, ohne dass ein Grund angezeigt wird.
2. Ob andere Server Einladungen für deine Mitglieder auf deinem Knoten platzieren dürfen. Das ist dein eingehender Notschalter, und er lässt sich aus jedem Zustand heraus auf Verweigern setzen.

Sie liegen absichtlich außerhalb dieser Datei, weil jedes reload die Föderations-Flags bedingungslos neu schreibt — ein hier gesetzter Wert würde eine Entscheidung, die du später getroffen hast, stillschweigend zurücksetzen.

Föderations-Flags

federation: true

federation: true schaltet den gesamten teilnehmenden Satz ein — code_lookup, open_link_claim, invitations, groups und multi_account. Jeder einzelne Flag-Schlüssel überschreibt die Kurzschreibweise.

Zwei Dinge, die zu wissen sich lohnen:

• Ein E-Mail-Transport ist eine harte Voraussetzung. Ohne smtp.host schaltet der Installer den gesamten Satz zwangsweise ab und sagt dir das.
• Die Beispieldatei setzt jedes Flag explizit auf false. Kopierst du sie unverändert, bekommst du einen Knoten mit abgeschalteter Föderation, obwohl ein Knoten mit sonst konfiguriertem SMTP standardmäßig eingeschaltet wäre. Setze sie bewusst.

Was jede Schnittstelle offenlegt, und warum zwei davon Sicherheitsbefunde waren, steht im Abschnitt Föderierter Server. Lies ihn, bevor du sie einschaltest.

WebFinger-Auffindung ist immer an. Ein Knoten muss auffindbar sein, um zu föderieren.

Oberflächen

Welche Web-Oberflächen dieser Knoten unter deiner Domain bereitstellt. Nutze die Blockform; die Inline-Form my: { enabled: true } wird nicht geparst.

surfaces:
  admin:
    enabled: true
  my:
    enabled: false
  verify:
    enabled: false
  provider:
    enabled: false
  status:
    enabled: false
  business:
    enabled: false
    # host: verify.example.com   # Domain-Override je Oberfläche

admin ist standardmäßig an und kann nie gestoppt werden — sie ist die Wiederherstellungs-Oberfläche. Jede aktivierte Oberfläche wird auf der Box gebaut und braucht einen eigenen DNS-A-Record.

Branding

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

Name, Farbe und Logo werden in den signierten Knoteninformationen veröffentlicht und auf die eigenen Inhalte des Knotens angewendet — E-Mails, Hilfe, Onboarding.

Optionale Integrationen

Alles hier ist optional. Lässt du einen Schlüssel leer, ist diese Funktion einfach aus: Der Knoten läuft trotzdem, und sowohl die Installationszusammenfassung als auch tc-operator status zeigen, welche Integrationen an sind und welche aus. Nichts scheitert lautlos. Diese Schlüssel besorgst du dir selbst, für deine eigene Installation; Trusted Codes bekommt sie nie zu sehen.

Integration	Schlüssel	Leer bedeutet
MaxMind — Geografie und Betrugsbewertung bei Anmeldungen und Abfragen	integrations.maxmind.account_id, license_key	Anmeldungen laufen unbewertet durch, also fail-open
KI-Chat	integrations.ai.mistral_api_key oder gemini_api_key	der Assistent ist aus
Metabase — eingebettete Dashboards in der Admin-App	integrations.metabase.site_url, embedding_secret	Dashboards nicht verfügbar

Die MaxMind-Voreinstellung lohnt einen zweiten Blick. Für einen Knoten, der Anmeldungen blockieren soll, wenn die Bewertung nicht verfügbar ist, statt sie durchzulassen, gibt es einen eigenen Parameter.

Abrechnung und Mobile Push sind zentral-only und haben hier keine Einstellung.

Push-Relais

push_relay_server: app.trusted.codes

Ein Föderationsserver-Name, keine URL. Dein Knoten besitzt die Push-Tokens seiner Nutzer, aber die Push-Zugangsdaten der gemeinsam genutzten Mobile App gehören Trusted Codes, dein Knoten kann also nicht direkt mit den Push-Diensten der App Stores sprechen. Ist das gesetzt, reisen Pushes als signierte Föderations-Umschläge durch das Relais.

Das Relais sieht ein Token, eine Uhrzeit und den Namen deines Servers. Nie Inhalt. In dieser Version reisen nur stille „Aufwachen und synchronisieren”-Anstöße; das Gerät holt dann die echten Daten von deinem Knoten und stellt sie dar. Die Konsequenz ist real: Deine Nutzer bekommen Hintergrund-Sync-Weckungen, keinen vom Server gesendeten Benachrichtigungstext. Sichtbare Hinweise erscheinen, wenn die App in den Vordergrund kommt und synchronisiert.

Lässt du es ungesetzt, bleiben direkte Sendungen bestehen, was funktioniert, bis die Push-Sicherheit plattformweit aktiviert ist. Fällt Push vollständig aus, geht nichts kaputt — Clients gleichen sich über Vordergrund-Abgleiche an. Push ist in diesem Produkt nie geschäftskritisch.

Eine Änderung auf einen laufenden Knoten anwenden

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

Stell es dir so vor, dass der ganze Knoten auf das gebracht wird, was die Datei jetzt sagt. Es verifiziert SMTP erneut gegen den lebenden Provider, bevor irgendetwas angewendet wird, rendert secrets.env aus der Datei neu, lässt Docker genau die Container neu erstellen, deren Einstellungen sich geändert haben, wendet die datenbankseitigen Einstellungen erneut an (Föderations-Flags, Oberflächen-Umschalter, Branding, Portal-URLs), signiert die veröffentlichten Informationen des Knotens neu, lädt den Proxy per Hot-Reload neu und testet sich selbst.

Erzeugte Geheimnisse — die JWT-Schlüssel, die Verschlüsselungsschlüssel, die Föderationsidentität — werden von einem Reload nie rotiert. Eine unveränderte Konfiguration ist ein No-Op, es ist also jederzeit sicher, es auszuführen.

Abgedeckt: smtp, auth, integrations, branding, surfaces, die Föderations-Flags, push_relay_server, sowie die Registry- und Lizenz-Overrides.

Was reload nicht tut

• home_server lässt sich nicht neu laden. Es zu ändern ist ein Identitätswechsel — DNS, TLS, Registry-Aufnahme. Reload verweigert und verweist auf die Installation.
• admin_email wird nur teilweise angewendet. Reload aktualisiert die Kontaktadresse des Zertifikats. Ein neues Admin-Konto braucht tc-operator add-admin --email <adresse>.
• Eine neu aktivierte Oberfläche wird nicht gebaut. Reload warnt und verweist auf tc-operator service start <oberfläche>, was sie baut und bereitstellt.
• Reload ist maßgeblich für Oberflächen. Jeder Ad-hoc-Umschalter, der seit dem letzten Abgleich in der Admin-App vorgenommen wurde, wird auf das zurückgesetzt, was die Datei erklärt. Die Installation verhält sich genauso.
• Neuer Code und neue Migrationen reisen nie per reload. Das ist Aktualisieren.