Umgebungsvariablen
Alle Einstellungen des Servers stehen in der .env neben docker-compose.selfhost.yml. Die Vorlage .env.example nennt jeden Eintrag mit einer kurzen Erklärung; dieser Artikel ordnet die wichtigsten. Eine geänderte .env wirkt nach docker compose -p workoffice -f docker-compose.selfhost.yml up -d. Neue Einträge nach einer Aktualisierung übernimmt scripts/env-abgleich.sh (siehe Aktualisieren).
Die .env enthält alle Schlüssel: chmod 600, nie einchecken, aber immer mitsichern.
Pflicht
| Eintrag | Bedeutung |
|---|---|
POSTGRES_PASSWORD | Eigentümer der Datenbank. Erzeugen mit openssl rand -hex 24 |
APP_DB_PASSWORD | Anwendungsbenutzer ohne Sonderrechte (Name: APP_DB_USER, Vorgabe workoffice_app). Ebenfalls Hex |
JWT_SECRET | signiert die Anmeldungen; im Betrieb mindestens 32 Zeichen, sonst startet die API nicht. openssl rand -base64 48 |
GEHEIMNIS_SCHLUESSEL | verschlüsselt Geheimnisse der Betriebe in der Datenbank. Leer wird er aus JWT_SECRET abgeleitet – dann macht ein neues JWT_SECRET sie unlesbar. openssl rand -base64 32 |
Ohne die ersten drei startet der Verbund gar nicht erst. Vorgabewerte gibt es bewusst nicht: Ein mitgeliefertes Geheimnis ist ein öffentlich bekanntes.
Adresse und Zugang
| Eintrag | Bedeutung |
|---|---|
APP_URL | die Adresse, unter der die Oberfläche aufgerufen wird – mit https://, sobald Caddy davor steht. Steht in Links aus Mails |
PORTAL_URL | Adresse für geteilte Belege und das Kundenportal; leer = APP_URL |
WEB_BIND, WEB_PORT | 127.0.0.1 bzw. Port der Oberfläche (Vorgabe 3100) |
SIGNUP_OPEN | false: Neue Betriebe können sich nicht mehr selbst registrieren |
ENABLE_API_DOCS | true: OpenAPI-Beschreibung unter /api/docs (siehe Einstieg) |
Fest in der Compose-Datei
Einige Werte setzt docker-compose.selfhost.yml selbst, sie gehören nicht in die .env: NODE_ENV=production, der Port der API (4100), STORAGE_DIR=/data/ablage – die Dateiablage, die im Volume ablage liegt – sowie DATABASE_URL und DATABASE_URL_MIGRATIONS, die aus den Passwörtern oben gebildet werden. STORAGE_DIR in der .env.example gilt nur für die Entwicklung ohne Docker.
SMTP_HOST, SMTP_PORT (Vorgabe 587), SMTP_USER, SMTP_PASSWORD, SMTP_SECURE, MAIL_FROM – siehe E-Mail des Servers. Ohne SMTP_HOST werden Mails nur protokolliert.
| Eintrag | Bedeutung |
|---|---|
MAIL_MARKE | Name vor dem Bindestrich der Systemmails („WorkOffice Pro - Support“); leer = Vorgabe, und ein eigener Name in MAIL_FROM bleibt stehen |
MAIL_ABSENDER_<ART> | eigener Name und/oder eigene Adresse je Art: INFO, SUPPORT, EINLADUNG, ERINNERUNG, VERTRIEB, KUNDENPORTAL, STEUERBERATER, BANK, SYSTEM, PARTNER, ABRECHNUNG – eine eigene Adresse muss das Konto als Alias kennen |
BETRIEB_MAIL_UEBER_SERVER | Mails der Betriebe an ihre Kunden ohne eigenen Mailserver über das Konto des Servers; leer = auf dem eigenen Server ja |
MAIL_INTERNE_SERVER | true: Mailserver der Betriebe im eigenen Netz erlauben, etwa ein Mail-Relay im Haus |
Schnittstellen und Webhooks
| Eintrag | Bedeutung |
|---|---|
WEBHOOK_PRIVATE_KEY | Signaturschlüssel der Webhooks der Lexware-kompatiblen Schnittstelle (ältere WorkTime-Fassungen, andere Programme); ohne ihn stellt der Server im Betrieb keine zu – sie warten, bis einer eingetragen ist. Die direkte Verbindung „Mit WorkTime verbinden“ braucht ihn nicht, sie signiert mit einem eigenen Geheimnis je Verbindung |
WEBHOOK_INTERNE_ZIELE | true: Webhooks auch an Adressen im eigenen Netz |
WEBHOOK_HTTP_ERLAUBT | true: Webhooks auch ohne https:// |
Fachliche Dienste
| Eintrag | Bedeutung |
|---|---|
FINTS_PRODUKT_ID, FINTS_INSTITUTE_DATEI | Bankanbindung über FinTS (Sparkassen, Volksbanken …); ohne Produktnummer geht nur Revolut |
BANKABRUF_STUNDEN | so oft werden Umsätze abgeholt (Vorgabe 6) |
BELEGEINGANG_GLEICHZEITIG, BELEGEINGANG_ZEITLIMIT_MS | Texterkennung der Belege: gleichzeitige Erkennungen (Vorgabe 1), Zeitlimit je Beleg |
BELEGEINGANG_SEITEN_OCR | höchstens so viele Seiten eines Belegs per Texterkennung lesen (Vorgabe 5) |
OCR_SPRACHDATEN_DIR | eigene Sprachdaten der Texterkennung (Ordner mit deu.traineddata); leer = die mitgelieferten |
BELEGEMPFANG_ADRESSE, IMAP_* | Belege per E-Mail empfangen; leer = abgeschaltet |
ADRESSSUCHE_URL, ADRESSSUCHE_PLZ_URL | Adressvorschläge beim Tippen (ab Werk Photon und OpenPLZ, gesendet wird nur der getippte Text); eigene Dienste eintragen oder mit aus abschalten. Jeder Betrieb kann sie zusätzlich unter Einstellungen → Firmendaten, Karte „Belege“, mit dem Schalter „Adressvorschläge aus dem Internet“ abschalten |
FISKALY_API_KEY, FISKALY_API_SECRET | Cloud-TSE für das Kassen-Terminal |
KASSE_SOFTWARE_VERSION | Version der Kassensoftware für die Mitteilung ans Finanzamt und die DSFinV-K (Vorgabe 1.0) |
KASSE_TSE=simulator mit KASSE_TSE_SIMULATOR=true | nur für ein Vorführsystem: simulierte TSE, Bons tragen „Testbon“ |
ARCHIVPRUEFUNG_TAGE | Abstand der automatischen Prüfung des GoBD-Archivs (Vorgabe 30) |
TELEGRAM_BOT_TOKEN, TELEGRAM_BOT_NAME, TELEGRAM_WEBHOOK_SECRET | Telegram-Benachrichtigungen; nur mit allen drei Werten und HTTPS von außen |
Lizenz und fertige Abbilder
| Eintrag | Bedeutung |
|---|---|
LICENSE_KEY | Lizenzschlüssel WOPRO-…; leer lassen, wenn er in der Oberfläche eingetragen wird |
LICENSE_SERVER_URL | Adresse des Lizenzservers; die Vorgabe https://license.workoffice-pro.de steht schon in der Compose-Datei |
LIZENZ_PFLICHT | schaltet die Lizenzprüfung ein. In docker-compose.selfhost.yml ab Werk false; docker-compose.kunde.yml setzt fest true |
LICENSE_PUBLIC_KEY | öffentlicher Schlüssel des Lizenzservers als PEM in einer Zeile (Zeilenumbrüche als \n) – nur beim Bau aus dem Quellcode; mit docker-compose.kunde.yml liegt er als Datei lizenz/public.pem daneben |
WORKOFFICE_VERSION | bestimmte Fassung der fertigen Abbilder statt der neuesten |
Mit den fertigen Abbildern schaltet docker-compose.kunde.yml die Lizenzprüfung ein und hängt lizenz/public.pem ein – in der .env steht dann höchstens der Lizenzschlüssel. Wer nur mit docker-compose.selfhost.yml aus dem Quellcode baut, setzt LIZENZ_PFLICHT=true und LICENSE_PUBLIC_KEY selbst in die .env; die Compose-Datei reicht beides weiter, ebenso LICENSE_KEY und LICENSE_SERVER_URL. Siehe Lizenz.
Sicherung
SICHERUNG_ZIEL (rsync-Ziel) und SICHERUNG_HOCHLADEN (Upload-Befehl) liest nicht die Anwendung, sondern das Sicherungsskript direkt aus der .env. SERVERSTAND_VERZEICHNIS legt fest, wohin es seinen Stand schreibt. Siehe Sicherung.
Nur beim Hersteller – auf dem eigenen Server aus lassen
| Eintrag | wofür |
|---|---|
ABO_AKTIV, ABO_TARIFE, ABO_PROBE_TAGE, ABO_KULANZ_TAGE, ABO_MWST, ABO_FREI, STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET | die Abo-Abrechnung der Cloud |
BETREIBER | Betreiberbereich der Cloud |
DEMO_ZUGANG | öffentlicher Demo-Betrieb |
KOMBI_GEHEIMNIS, KOMBI_GEGENSTELLE_URL, KOMBI_ABSTAND_MS | Kombi-Rabatt zwischen den Cloud-Servern von WorkOffice und WorkTime |
LIZENZSERVER_URL und LIZENZ_… außer LIZENZ_PFLICHT | der Lizenzserver selbst |
Mit Lizenzpflicht schaltet WorkOffice Abo-Abrechnung, Demo-Betrieb und Kombi-Rabatt ohnehin ab, auch wenn in der .env etwas anderes stünde.
Was aus der .env ankommt
Docker Compose gibt einem Container nur die Einträge, die in der Compose-Datei unter environment stehen. docker-compose.selfhost.yml führt dort jeden Eintrag aus .env.example, den die API liest, mit seiner Vorgabe auf – was in der .env steht, kommt also im Container an, auch MAIL_MARKE, die Absender je Art, MAIL_INTERNE_SERVER, die Adresssuche und die Lizenz. Eine Prüfung in den Tests der API (apps/api/src/config/compose-umgebung.spec.ts) schlägt fehl, sobald ein neuer Eintrag dazukommt, den die Compose-Datei nicht weiterreicht.
Ausgenommen sind nur Werte, die in der .env nichts zu suchen haben: was die Compose-Datei fest setzt oder zusammensetzt (siehe Fest in der Compose-Datei), der Programmstand, den das Abbild mitbringt, und Einträge nur für die Entwicklung.