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: