Zum Inhalt

Konfiguration

Getrennte Datenbankrollen

DATABASE_URL ist die echte Anmeldung des laufenden Servers. MIGRATION_DATABASE_URL ist der Eigentümerzugang für Migrationen und die anschließende Rechtevergabe; der Server erhält diese Adresse nicht. Die App-Rolle darf Tabellen und Funktionen von Haben weder besitzen noch die Eigentümerrechte erben oder per SET ROLE erreichen. Ohne Superuser-, Rollenverwaltungs- und Datenbankanlage-Rechte kann sie lesen und schreiben, aber keine Sperr-Trigger abschalten. Auch temporäre Schattenrelationen und eigene Objekte im Schema sind gesperrt. Die Rollenverwaltung bleibt beim Betreiber; der App-Start legt keine Rolle an und ändert kein Passwort.

Neue Installationen verwenden die beiden Verbindungen aus den Vorlagen. createuser fragt das Passwort verdeckt ab; dafür ein eigenes Passwort aus dem Passwortmanager wählen, bei den gezeigten URLs nur Buchstaben und Ziffern. Es muss mit dem Passwort in DATABASE_URL übereinstimmen. Der Datenbanknutzer haben bleibt Eigentümer und Betreiberzugang für Backup, Restore und PostgreSQL-Upgrade.

Bestehende Installation umstellen: Zuerst ein Backup anlegen und die App stoppen. Die Rolle einmalig mit dem createuser-Befehl aus Docker Compose bzw. Quadlets › Starten anlegen. Bei Compose die bisherige Datenbankadresse in MIGRATION_DATABASE_URL übernehmen und DATABASE_URL auf den neuen App-Zugang setzen. Bei Quadlets den bisherigen Wert von haben-database-url als neues Secret haben-migration-database-url hinterlegen, haben-database-url mit dem App-Zugang ersetzen und die vorbereitete Secret-Zeile in haben-app.container einkommentieren; danach systemctl --user daemon-reload. Anschließend die App starten und unter Einstellungen › Export den Stand der Verbindung und „Kette prüfen“ kontrollieren. Die bisherigen Tabellen behalten ihren Eigentümer, Buchungen und Siegel bleiben erhalten.

Ohne zweite Adresse startet eine bestehende Konfiguration weiter mit dem bisherigen Zugang; Einstellungen melden dessen weitergehende Rechte. Bei ausdrücklich eingerichteter Trennung bricht ein fehlerhafter Zugang den Start ab, statt den Eigentümer für den Server zu verwenden.

Auch eine Login-Vorgabe session_replication_role=replica schaltet Trigger aus, ohne dass die App den Parameter selbst ändern darf. Haben erkennt den tatsächlich aktiven Modus und weist diesen Start vor der Migration zurück. Der Betreiber muss dann die Rollen- oder Datenbankvorgabe korrigieren; Haben überschreibt sie nicht.

Eine bloße Mitgliedschaft ohne nutzbare Vererbung, Rollenwechsel oder Verwaltungsrechte verhindert den Start nicht. Tatsächlich verfügbare ADMIN-Optionen gelten dagegen als Rollenverwaltungsrechte und sind für die App-Anmeldung nicht zulässig.

Extern verwaltete Datenbank, etwa CloudNativePG: Der Operator stellt beide Anmeldungen bereit. Die Eigentümerrolle darf ohne Superuser und ohne CREATEROLE arbeiten, muss aber Eigentümer der Haben-Objekte sein und die Schema- und Datenbankrechte vergeben können. Die App-Rolle braucht keine Mitgliedschaft in ihr. Beide Adressen müssen dieselbe Haben-Datenbank erreichen. Haben vergibt nach jeder Migration die benötigten Tabellen-, Sequenz- und Funktionsrechte, auch ohne neue Migration. Im dedizierten Haben-Datenbankkontext entfallen beim Umstieg die von PUBLIC geerbten Rechte zum Anlegen temporärer Tabellen und zum Erzeugen von Objekten in public; andere direkte oder geerbte unsichere Rechte muss der Operator vorher entfernen, auch Ausführungsrechte auf Serverdateifunktionen wie lo_import und lo_export. Eine Datenbank für weitere Anwendungen ist dafür ungeeignet.

Ein externer Eigentümer ohne CREATEDB reicht zum Migrieren, aber nicht für die eingebauten Restore-Werkzeuge: Sie legen Wegwerf-Datenbanken an und ersetzen beim Restore die bisherige Datenbank. Für diese Betreiberaufgaben einen dafür berechtigten Zugang bereitstellen oder die Sicherung und Wiederherstellung des Operators verwenden. Weder Backup noch Upgrade verwenden die eingeschränkte App-Rolle.

Umgebungsvariablen

Die App prüft ihre Variablen in apps/web/src/server/env.ts beim ersten Zugriff. Ein Fehler steht dann im Log von haben-app.

Variable Pflicht Bedeutung Beispiel
DATABASE_URL ja Echte PostgreSQL-Anmeldung der App; ohne zweite Adresse auch für Migrationen postgres://haben_app:…@haben-db:5432/haben
MIGRATION_DATABASE_URL nein Eigentümerverbindung nur für Migrationen und Rechtevergabe, siehe Getrennte Datenbankrollen postgres://haben:…@haben-db:5432/haben
BETTER_AUTH_SECRET ja Geheimnis für Sitzungen, mindestens 32 Zeichen Ausgabe von openssl rand -base64 32
BETTER_AUTH_URL ja Öffentliche Adresse, unter der Haben im Browser läuft. Bestimmt die Domain der Passkeys https://haben.example.de
OIDC_ONLY nein Betriebsart: false (Vorgabe) ausschließlich lokale Anmeldung, true ausschließlich SSO. Andere Werte verhindern den Start false
OIDC_ISSUER bei OIDC_ONLY=true Exakter Issuer des Anbieters; im Standardmodus ohne Wirkung https://auth.example.de
OIDC_CLIENT_ID bei OIDC_ONLY=true ID des vertraulichen Clients haben
OIDC_CLIENT_SECRET bei OIDC_ONLY=true Ursprüngliches Clientsecret, kein Hash –
OIDC_DISPLAY_NAME nein Anzeigename der SSO-Anmeldung Authelia
OIDC_SCOPES nein Scopes mit Leerzeichen; openid ist Pflicht, siehe unten openid profile email groups
OIDC_GROUPS_CLAIM nein Name des Gruppen-Claims in UserInfo oder ID-Token, ein einzelner Name oder eine URL, kein Ausdruck. Vorgabe groups groups
OIDC_GROUP_INHABER bei OIDC_ONLY=true Gruppe, deren Mitglieder Inhaber sind (exakt, groß-/kleinschreibungssensitiv) haben-inhaber
OIDC_GROUP_STEUERBERATUNG bei OIDC_ONLY=true Gruppe für den Lesezugang der Steuerberatung; muss sich von der Inhaber-Gruppe unterscheiden haben-steuerberatung
HABEN_ENCRYPTION_KEY ja Genau 32 Byte, base64-kodiert. Verschlüsselt ELSTER-Zertifikat, Zugangsdaten und die API-Schlüssel für Lexoffice und sevDesk Ausgabe von openssl rand -base64 32
HABEN_SETUP_CODE nein Fester Einrichtungscode für das Anlegen des Kontos (mindestens 8 Zeichen). Ohne ihn erzeugt Haben bei jedem Start einen neuen und schreibt ihn ins Log, solange es kein Konto gibt mein-einrichtungscode
ERIC_HOME nein Verzeichnis eines von Hand entpackten ERiC-Pakets; hat Vorrang vor dem heruntergeladenen. Ohne beides werden Prüfen und Senden simuliert /opt/eric
ERIC_DIR nein Ziel für das von Haben heruntergeladene ERiC. Standard data/eric; im Image /var/lib/haben/eric (Volume) /var/lib/haben/eric
ERIC_AUTO_INSTALL nein ja: fehlt ERiC, lädt der Container es beim Start (Zustimmung zu den Nutzungsbedingungen) ja
ERIC_VERSION nein Version, die ERIC_AUTO_INSTALL bzw. install-cli.ts ohne Versionsangabe lädt. Standard ist die von Haben vorgeschlagene 44.3.6.0
ERIC_DOWNLOAD_URL nein Andere Download-Adresse für ERiC, nur zum Testen. Standard https://download.elster.de/download/eric http://localhost:4556/eric
ERIC_SHA256 nein Erwartete SHA-256 des ERiC-Pakets (64 Hex-Zeichen). Stimmt sie nicht, bricht die Installation ab. Die Prüfsumme eines Downloads steht danach im Log und in HABEN_ERIC_SHA256 im ERiC-Verzeichnis 3f5a…
ERIC_LOG_DIR nein Logverzeichnis für ERiC. Ohne Angabe das temporäre Verzeichnis; im Image /var/lib/haben/eric-log /var/lib/haben/eric-log
ERIC_WORKER_PATH nein Pfad zum ERiC-Worker (packages/elster/src/worker.ts). Im Image gesetzt, sonst nicht nötig /app/packages/elster/src/worker.ts
ERIC_WORKER_COMMAND nein Befehl, der den ERiC-Worker statt der eigenen Laufzeit startet; worker.ts kommt als letztes Argument dazu. Mehrere Wörter durch Leerzeichen getrennt, ohne Anführungszeichen. Für ELSTER auf arm64 das Skript aus deploy/eric-x86_64/einrichten.sh, siehe ELSTER auf arm64 /opt/haben-x86_64/worker.sh
ELSTER_HERSTELLER_ID nein Eigene Hersteller-ID, genau fünf Ziffern. Mit ERiC 43 nötig für Prüfen, Test- und Echtübermittlung; ohne ERiC läuft alles simuliert 12345
DOCUMENTS_DIR nein Ablage der Belegdateien. Standard data/belege (relativ zum Arbeitsverzeichnis); im Image /var/lib/haben/belege /var/lib/haben/belege
ANTHROPIC_API_KEY nein Schaltet die KI-Auslesung von Belegen mit Claude ein sk-ant-…
EXTRACTION_BASE_URL nein Basis-URL eines KI-Dienstes mit OpenAI-kompatibler Schnittstelle, selbst betrieben (Ollama) oder in der Cloud (OpenRouter, OpenAI, …). Ist sie gesetzt, liest nur dieser Dienst Belege aus, auch wenn ANTHROPIC_API_KEY gesetzt ist (OpenAI-kompatible Schnittstelle) http://host.docker.internal:11434/v1, https://openrouter.ai/api/v1
EXTRACTION_MODEL mit EXTRACTION_BASE_URL Name des Vision-Modells beim Dienst, so wie der Dienst ihn schreibt. Fehlt er, startet die App nicht qwen2.5vl:7b
EXTRACTION_API_KEY nein Schlüssel des Dienstes, falls er einen verlangt; geht als Authorization: Bearer … mit …
EXTRACTION_PROVIDER nein Anbieter ausdrücklich wählen: anthropic oder openai-compatible. Ohne Angabe gilt der eigene Dienst, sobald EXTRACTION_BASE_URL gesetzt ist openai-compatible
EXTRACTION_TIMEOUT_SECONDS nein Wartezeit auf den eigenen Dienst je Beleg, 5 bis 3600. Standard 300 600
EXTRACTION_MAX_PAGES nein So viele PDF-Seiten gehen höchstens als Bild an den eigenen Dienst, 1 bis 20. Standard 4 2
EXTRACTION_INPUT nein Was bei PDFs an den eigenen Dienst geht: text-und-bild (Text der Seiten aus der Textschicht und Seitenbilder), text (nur Text, für ein reines Textmodell) oder bild (nur Seitenbilder). Standard text-und-bild, siehe KI-Auslesung text
EXTRACTION_EXTRA_BODY nein Zusätzliche Felder im Request-Body an den eigenen Dienst, als JSON-Objekt. Für Modelle, die sonst ihr Antwortbudget mit Denken verbrauchen (reasoning_tokens), etwa DeepSeek über ein Gateway: {"reasoning_effort":"none"}. model, messages, stream und response_format setzt Haben selbst und überschreibt sie. Ohne Angabe geht der Body unverändert raus, siehe KI-Auslesung {"reasoning_effort":"none"}
LAYOUTS_MAX_COUNT nein Höchstzahl eigener Belegvorlagen (Eigene Belegvorlagen), damit niemand die Installation überlädt. Ohne Angabe unbegrenzt 20
LAYOUTS_MAX_MB nein Speicher für eigene Belegvorlagen in MB, Quelltexte und freigegebene Pakete zusammen. Ohne Angabe unbegrenzt; eine einzelne Vorlage hat höchstens 256 KB 50
LAYOUTS_PACKAGES_URL nein Andere Quelle für die Typst-Pakete eigener Belegvorlagen, etwa ein Spiegel ohne Zugang ins Internet; darunter je Paket <name>-<version>.tar.gz. Standard https://packages.typst.org/preview https://spiegel.example/typst/preview
HABEN_SCHEDULER nein off schaltet die stündlichen Hintergrundjobs ab (u. a. wiederkehrende Rechnungen, Dauerbelege, Kontoabruf, ELSTER-Postfach, Umrechnungskurse, Belege per E-Mail, Fristen-Erinnerungen), etwa für eine zweite Instanz auf derselben Datenbank off
HABEN_FIRMEN nein Instanzen der eigenen Firmen für die Zeile „Firma wechseln“ in der Navigation: Name und Adresse je Firma, Format unter Firma wechseln siehe dort
HABEN_FIRMENPORTAL_URL nein Nur mit SSO: Adresse des Firmenportals, in das die Zeile „Zum Firmenportal“ führt, statt „Firma wechseln“ mit der Liste aus HABEN_FIRMEN (nicht beides), siehe Firmenportal –
ENABLE_BANKING_APP_ID nein Application ID der Enable-Banking-Anwendung. Schaltet zusammen mit dem Schlüssel den automatischen Kontoabruf ein. Einfacher: unter Einstellungen › Bank hochladen; das geht dann vor 0b7c3f1e-…
ENABLE_BANKING_KEY_FILE nein Pfad zum privaten Schlüssel (PEM) der Anwendung. Bei Compose und Quadlets fest /run/secrets/enablebanking.pem /run/secrets/enablebanking.pem
ENABLE_BANKING_KEY nein Alternativ der Schlüssel selbst; Zeilenumbrüche als \n erlaubt -----BEGIN PRIVATE KEY-----\n…
ENABLE_BANKING_API_URL nein Andere Basis-URL der API, nur zum Testen. Standard https://api.enablebanking.com http://localhost:4555
GOOGLE_PLAY_TOKEN_URL, GOOGLE_PLAY_STORAGE_URL nein Andere Adressen für Anmeldung und Cloud Storage beim Abruf der Google-Play-Berichte, nur zum Testen. Standard https://oauth2.googleapis.com/token bzw. https://storage.googleapis.com http://localhost:4556
APP_STORE_CONNECT_URL nein Andere Basis-URL von App Store Connect beim Abruf der Finanzberichte, nur zum Testen. Standard https://api.appstoreconnect.apple.com http://localhost:4557
LEXOFFICE_API_URL nein Andere Basis-URL der Lexware-Office-API. Standard https://api.lexware.io/v1 https://api.lexoffice.io/v1
SEVDESK_API_URL nein Andere Basis-URL der sevDesk-API, nur zum Testen oder falls sevDesk die Adresse ändert. Standard https://my.sevdesk.de/api/v1; Ablauf in Umzug aus sevDesk https://my.sevdesk.de/api/v1
FASTBILL_API_URL nein Andere Adresse der FastBill-API, nur zum Testen. Standard https://my.fastbill.com/api/1.0/api.php; Ablauf in Umzug aus FastBill https://my.fastbill.com/api/1.0/api.php
PORT nein Port des App-Servers, im Image 3000 3000
HABEN_COMMIT nein Commit, aus dem das Image gebaut ist; haben status zeigt ihn hinter der Version (Image). Im Image aus dem Build-Argument HABEN_COMMIT gesetzt, ohne Angabe leer 0123abc4567def890123abc4567def890123abcd
HABEN_EINVOICE_DIR nein Verzeichnis von packages/einvoice (Typst-Vorlage und Schriften für das Rechnungs-PDF). Im Image gesetzt /app/packages/einvoice

Bei Compose setzt compose.yml diese Variablen aus .env (DATABASE_URL und MIGRATION_DATABASE_URL wie eingetragen, ohne DATABASE_URL den bisherigen Zugang aus DB_PASSWORD; BETTER_AUTH_URL aus DOMAIN, BETTER_AUTH_SECRET aus AUTH_SECRET, HABEN_ENCRYPTION_KEY aus ENCRYPTION_KEY). Bei den Quadlets kommen die geheimen Werte aus Podman Secrets, der Rest aus haben.env; für den Datenbank-Container setzt das Quadlet POSTGRES_USER=haben und POSTGRES_DB=haben, das Passwort kommt aus dem Secret haben-db-password.

In den App-Container reicht compose.yml nur die Variablen durch, die dort unter app › environment stehen. Andere, etwa HABEN_SETUP_CODE, HABEN_SCHEDULER, LEXOFFICE_API_URL, FASTBILL_API_URL oder SEVDESK_API_URL, wirken in .env allein nicht; trag sie in der compose.override.yml beim Dienst app unter environment ein. Bei den Quadlets gelten alle Zeilen aus haben.env.

Datenablage

Was Wo
Buchungen, Rechnungen (PDF und XML), Voranmeldungen mit ERiC-Protokoll, Audit-Log, verschlüsseltes ELSTER-Zertifikat, verschlüsselte API-Schlüssel für Lexoffice und sevDesk PostgreSQL, Volume haben-db
Belegdateien und aus Lexoffice übernommene Dateien Volume haben-belege (DOCUMENTS_DIR), abgelegt unter dem SHA-256 der Datei (ab/abcdef…)
ERiC, von Haben heruntergeladen Volume haben-eric (Compose: eric), im Container /var/lib/haben/eric (ERIC_DIR). Lässt sich jederzeit neu laden, nicht im Backup
ERiC-Logs Volume haben-eric-log (Compose: eric-log), im Container /var/lib/haben/eric-log (ERIC_LOG_DIR). Nur zur Fehlersuche, nicht im Backup
TLS-Zertifikate von Caddy Volume haben-caddy
Backup (restic-Repository), wenn RESTIC_REPOSITORY nicht gesetzt ist Volume haben-backups (Compose: backups), im Backup-Container /backups

Bücher und Aufzeichnungen bewahrst du 10 Jahre auf, Buchungsbelege wie Rechnungen 8 Jahre (§ 147 Abs. 3 AO, siehe Aufbewahrung). Beide Volumes mit Buchhaltungsdaten gehören deshalb ins Backup.

Letztes Update: