docs / admin / admin-basics.md

Administration

Dieser Abschnitt deckt den Alltag und den Betrieb einer selbst gehosteten entrytwo-Instanz ab.

Benutzer, Rollen und Zugriff

entrytwo hat drei Rollen:

ADMIN: Voller Zugriff. Kann Benutzer, Einladungen, Perioden, Steuersätze, Einstellungen, Updates, Backups, Bank-Feeds und KI-Konfiguration verwalten. Kann auch alle Accountant-Arbeit erledigen.
ACCOUNTANT: Normale Buchhaltungsarbeit (Journalbuchungen, Abstimmung, Rechnungen, Claims, Kontakte usw.). Keine Benutzer- oder Systemverwaltung.
VIEWER: Nur-Lese-Zugriff auf die Bücher.

Erster Admin (Bootstrap)

Auf einer frischen Installation wird der allererste angelegte Benutzer ADMIN. Das läuft über die Anmeldeseite oder das Admin-Panel, wenn noch kein Admin existiert.

Danach gelten normale Benutzeranlage und Einladungen.

Siehe:

docs/getting-started/first-steps.md
docs/getting-started/installation.md (Bootstrap-Abschnitt)

Benutzer anlegen und verwalten

Gehe zu Admin → Users.

Dort kannst du:

Neue Benutzer anlegen (in der Entwicklung oft direkt; in Produktion meist über Einladungslinks).
Rollen zuweisen oder ändern (ADMIN / ACCOUNTANT / VIEWER).
Benutzer deaktivieren.
Sicherheitschecks: Du kannst den letzten verbleibenden ADMIN nicht entfernen oder herabstufen.

Einladungen

Admins erzeugen Einladungslinks unter Admin → Benutzer. Token / URL werden bei der Erstellung angezeigt (und per E-Mail versendet, wenn SMTP konfiguriert ist).

Einladungen tragen eine Rolle (ADMIN, ACCOUNTANT oder VIEWER) und ein Ablaufdatum.

Die eingeladene Person muss sich mit genau der eingeladenen E-Mail (Groß-/Kleinschreibung egal) über Google, Microsoft oder Magic Link anmelden. Ein anderes OAuth-Konto wird abgelehnt und legt keinen Benutzer an.

Authentifizierungsoptionen

Magic Link per SMTP (gebrandete E-Mail, einmalig, 30 Minuten). Frühere ungenutzte Links für dieselbe Adresse werden bei einem neuen Link ungültig.
OAuth: Google und/oder Microsoft Entra ID, wenn Client-ID und Secret gesetzt sind. Redirect-URIs: {AUTH_URL}/api/auth/callback/google und .../microsoft-entra-id.
Entwicklung: Sofort-Anmeldung per E-Mail (/api/auth/dev) nur wenn NODE_ENV !== production. Auf einem echten VPS-Produktionsdeploy nicht verfügbar.
Nach dem Bootstrap brauchen neue Benutzer eine aktive Einladung. Bestehende Benutzer melden sich ohne neue Einladung an.
Abmelden: Einstellungsmenü (Zahnrad) in der oberen Leiste.

2FA (TOTP) wird unterstützt. In Produktion müssen ADMIN-Benutzer TOTP einrichten, bevor die App nutzbar ist. Wiederherstellungscodes sind einmalig.

Produktions-Checkliste (HTTPS, AUTH_URL, AUTH_TRUST_HOST, Health auth.productionReady): im App-Repo docs/VPS-Auth-Install.md.

Buchhaltungsperioden

Admin → Periods

Du kannst Perioden öffnen und schließen. Das Schließen signalisiert, dass die Bücher für diesen Zeitraum finalisiert sind (nützlich für Reporting, Steuer und Audit-Komfort).

Das Git-Modell erlaubt weiterhin den Blick in die Historie einer geschlossenen Periode, und du kannst immer Korrekturbuchungen auf einem Branch oder per Rollback + neue Commits erzeugen.

Bank-Feeds und Processor-Integration

Admin → Bank Feeds

Unterstützte Live-Processor-Feeds umfassen Stripe (und PayPal in manchen Konfigurationen).

Feed verbinden mit Credentials (verschlüsselt mit ENCRYPTION_KEY gespeichert).
Transaktionen synchronisieren.
Hochkonfidente Payouts/Charges können optional einfache Journalbuchungen erzeugen (oft default aus, um die Chat-Sperre zu respektieren).

Für andere Banken und Karten ist der Hauptweg das Hochladen von Auszügen oder Transaktionstabellen über den Chat (PDF oder eingefügte Daten).

Siehe auch den KI-Workflow in docs/ai/using-the-ai.md.

Steuerkonfiguration

Admin → Tax

Steuersätze für deine Jurisdiktionen definieren (z. B. DE 19 %/7 %, AT 20 %, US-CA 8,25 % usw.).

Diese Sätze fließen in Journalbuchungen, Rechnungen und Claims ein.

Default-Jurisdiktion in den Firmeneinstellungen setzbar.

Firmeneinstellungen

Admin → Company (oder über Onboarding/Bootstrap)

Firmenname
Basiswährung
Adresse / Jurisdiktion
Weitere Präferenzen

Das beeinflusst Berichte, FX-Handling und Rechnungsausgabe.

Backup & Restore (portable Vollsystem-Backups)

entrytwo bietet ein portables Vollbackup-Format (.etbackup).

Ort: Admin → Backup

Was ein Backup enthält

Jede Datenbanktabelle (Journalbuchungen, Kontakte, Benutzer, Settings, Events, Branches, Tags usw.)
Hochgeladene Dateien (Belege, Auszüge, Rechnungs-PDFs)
Manifest mit SHA-256-Checksummen und Zeilenzahlen zur Integritätsprüfung

Schlüsseleigenschaften

Restore ist ein vollständiger Ersatz der Daten der Zielinstanz.
Gedacht für Disaster Recovery oder Migration auf eine frische Installation.
Die Zielinstanz muss denselben ENCRYPTION_KEY nutzen, der bei der Backup-Erstellung aktiv war (sonst lassen sich verschlüsselte Bank-Credentials und Ähnliches nicht entschlüsseln).
Das Manifest wird vor dem Restore validiert.

So nutzt du es

Admin → Backup öffnen.
Vollbackup exportieren (oder per Hintergrundjob auslösen).
.etbackup-Datei herunterladen und sicher off-host lagern.
Auf neuer oder Ersatzinstanz mit korrektem ENCRYPTION_KEY:
- Import-/Restore-Flow öffnen und Archiv hochladen.
- System prüft Checksummen und Zeilenzahlen und restored dann.

Weitere Hinweise

Für reines DB-Backup kannst du weiterhin pg_dump / psql nutzen, verlierst aber verknüpfte Dateien und die praktischen Manifest-Checks.
Updates erzeugen automatisch ein Pre-Update-Vollbackup (siehe Updates).
Siehe auch entrytwo_v1/docs/ENCRYPTION-KEY-ROTATION.md, falls du den Encryption Key jemals ändern musst.

Self-Hosted Updates

entrytwo nutzt ein sicheres, pro-Kunden Update-Delivery-System.

Ablauf auf hoher Ebene:

Releases werden als Docker-Images gebaut und mit cosign signiert (keyless oder gepinnter Public Key).
Ein signiertes Manifest beschreibt die neueste verfügbare Version.
Die App (oder ein isolierter Updater-Sidecar) zieht den exakten Digest, prüft die Signatur, erzeugt ein volles Pre-Update-Backup, führt Migrationen aus, macht einen Healthcheck und kann bei Fehler automatisch rollen.
Die laufende App wird niemals abgeschaltet, nur weil die Wartung ausgelaufen ist. Sie erhält einfach keine neuen Versionen mehr.

Tiefes Technikdokument:

entrytwo_v1/docs/Self-Hosted-Update-Delivery.md

In der UI:

Admin → Update zeigt aktuellen Status, verfügbares Update und lässt dich ein Update auslösen.
Vor dem Anwenden wird automatisch ein Vollbackup erzeugt.
Fortschritt und Rollback-Infos werden angezeigt.

Hinweis Geschäftsmodell (siehe Lizenzierung unten):

Unbefristete Lizenz = du besitzt die Version, die du hast, für immer.
Jährliche Wartung = Anspruch auf neue Versionen + Support.

Lizenzierung und Trial

entrytwo nutzt ein Modell 30-Tage-Trial + unbefristete Lizenz.

Trial

Startet bei erster Nutzung einer frischen Instanz (firstUseAt).
Volle Funktionalität für 30 Kalendertage.
Sichtbarer Trial-Indikator.
Nach 30 Tagen ohne gültige bezahlte Lizenz: blockierende Paywall für den Normalbetrieb.

Lizenzaktivierung („einmal verifizieren, für immer vertrauen“)

Du kaufst eine Lizenz (einmalig) und erhältst einen signierten Lizenzschlüssel.
Schlüssel einmal in der App eingeben.
App prüft ihn (Signatur + optional Online-Bestätigung).
Bei Erfolg wird der Key dauerhaft für dieses Deployment gespeichert.
Danach lesen alle Status-, Paywall- und Update-Entscheidungen nur das gespeicherte Flag. Der externe Verifikationsservice wird nie wieder aufgerufen.
Die App läuft nach der Lizenzierung voll offline.

Nach der Lizenzierung

Die Instanz ist dauerhaft für dieses Deployment lizenziert.
Die laufende App wird niemals abgeschaltet.
Neue Updates hängen an aktiver Wartung (siehe Self-Hosted Updates).
Abgelaufene Wartung → du behältst die letzte erhaltene Version.

Vollständige Policy und Implementierungsdetails:

entrytwo_docs/Licensing-and-Trial.md
Code-Kommentare in lib/license.ts, /api/license/activate usw.

In der UI:

Top-Bar zeigt Trial-Status oder Lizenzzustand.
License-Button / Modal zum Eingeben eines Keys.
Update-Seite respektiert die Lizenzierung (versteckt Verfügbarkeit oder zeigt Meldungen bei unlizenziert nach Trial).

Sicherheitsbasics für Admins

Starkes AUTH_SECRET (≥ 32 Zeichen) und NODE_ENV=production in Produktion.
Öffentliche HTTPS-Origin in AUTH_URL / APP_PUBLIC_URL; AUTH_TRUST_HOST=true hinter Reverse-Proxy.
Mindestens eine echte Anmeldemethode in Produktion: volles SMTP und/oder Google und/oder Microsoft (Dev-Sofort-Login ist aus).
GET /api/health prüfen: ready: true und auth.productionReady: true.
ENCRYPTION_KEY (64 Hex-Zeichen) setzen, bevor Bank-Feeds genutzt werden.
Docker-Socket / Updater-Token in Produktions-Deployments schützen.
Regelmäßige Off-Host-Backups (Admin → Backup und/oder pg_dump).
Audit-Log und Git-Historie regelmäßig prüfen.

Für Update-Signing und Threat Model: Self-Hosted-Update-Delivery.md. Für Auth-Go-Live: VPS-Auth-Install.md im App-Repo.

Wo du was findest

Die meisten Admin-Funktionen: Admin-Menü (linke Sidebar im Admin-Bereich).
Backup: Admin → Backup
Update: Admin → Update
Users: Admin → Users
Periods, Tax, Bank Feeds, AI settings, Webhooks, Automation, Chart of Accounts: unter Admin.
Lizenzstatus / Aktivierung: Top-Bar oder Admin-Bereich.

Viele dieser Bereiche exposen Daten oder Aktionen auch über den Chat (wo sinnvoll).

Weiterführende Lektüre

docs/getting-started/installation.md
docs/getting-started/first-steps.md
entrytwo_v1/docs/SETUP.md (technischere Setup-Details)
entrytwo_v1/docs/Self-Hosted-Update-Delivery.md
entrytwo_docs/Licensing-and-Trial.md
entrytwo_v1/docs/ENCRYPTION-KEY-ROTATION.md

Admin-Arbeit ist bewusst begrenzt, weil die Produktphilosophie lautet: „Die KI macht die langweilige repetitive Arbeit; Menschen steuern und prüfen.“